1 - In 12 years of Domino development at over 30 Fortune 1000 organizations, I've never found the whole variable naming standards thing to be relevant. *Field* naming standards can be important, but in-memory variables? That's C techniques defined by people that have to memory manage. When you're working in LS or Java, it's just a burden on developers that doesn't contribute to productivity, and saves trivially on maintenance.

If your team needs a variable name flag to know that in..

While Not (cur is nothing)
'do something with cur
call cur.Save(false, false)
set cur = x.getNextDocument(cur)
Wend

..."cur" is a NotesDocument and "x" is a collection, I'd reconsider hiring practices.

I don't mean to sound like I'm trying to shoot down good ideas -- I just think that SO much effort is placed on essentially superficial factors in business software development. Naming standards are important for stored data, but for in-memory variables for procedures that are rarely more than 2 pages long? What's the point?

If you're writing Windows, or Notes itself, or Linux, these things are important. If you're writing a long-term product on the Domino platform, they *might* be important. But for the vast majority of business development, what's important is a) successfully meeting business needs and continually adapting to them (since they always change), and b) ensuring reasonable scalability across the enterprise in anticipation of future deployment. I've seen hundreds of applications developed with all the standards you can shake a stick at that still performed poorly and failed to adapt to changing business conditions.

The methodologies that made sense when you were conducting 2 year COBOL projects don't make sense when you're working with a cross-platform RAD system.

2 - Nathan,
I think Christopher meant the usual audit habits: they look for quantity of documentation and the structure. They don't read code and don't understand it. I was subject to audits while working in a bank. It was always fun, because they never raised the true issues (e.g. do the developers have manager access to critical production data) but were crazy about a rigid documentation structure. I was regularily asked for a ER-Schema of our Notes databases.
stw

3 - Personally, I think Notes/Domino development breaks the rules about a lot of project management. I eschew specs and design documentation, simply because you'll spend more time writing down what you want than you will building it. Users universally respond better to a demonstration than they do to a description, so prototype.

Obviously, if you're looking to build a global CRM system, or an interdepartmental CMS application, you can't prototype the ENTIRE thing. In that case, create a loose plan that splits general objectives into digestable chunks, then prototype those.

Here's the problem with over-developed specifications: though they might describe exactly what you want, they rarely, if ever, describe how to get there. And when a large team under a tight deadline works off a complex spec, they'll right bad code to achieve goals inside the deadline. However, the same team allowed to iteratively develop a system will tend to write more maintainable and better performing code, because they know they're going to have to live through more QA/Production lifecycle updates. You get more solid code from multiple prototyping cycles than you do from monolithic development basically because the system you put into production is effectively a version 3.1 instead of a 1.0.

The basic problem with this strategy is really SELLING it. That is, when you lay out a project as requiring a team of 10 people who will do 6 months of user surveys to develop raw materials, then write a project specification for 3 months, then code for 9 months, then QA for 4 months, then install for 1 month, that SOUNDS like a strategic investment.

If instead, you propose a team of 3 people develop a shell system in 2 months, go through a user review iteration, modify according to feedback for another 2 months, go through another user iteration, modify and release for limited functionality a version 1.0, the plan subsequent cycles all the way through version 3 a year later... well, that sounds like craziness! How are you supposed to plan a budget for that? How are you supposed to tell customers when they'll be able to get online? How are you supposed to schedule training?

Never mind that it's cheaper, gets you a solution faster, generates more reliable code and allows for improved user participation. It sounds like absolute chaos, and since middle managers tend to think like communist planners, it doesn't fit in with their vision of a "well run strategic platform."

Sorry for the rant. It's just another reminder why I need out of this industry. :) Anyway, seriously, you can get great results if you can convince higher-ups to let you work this way. It also tends to keep your people more motivated, since you can get positive feedback on development results much sooner.

4 - A very simple, yet effective "tool" is to create a discussion database (use the standard template) specific to the project you are working on. Grant everybody involved in the project access to it, and then use it.

It may seem trite, but I've found that it works very well.
-Devin

5 - I'm also looking for one or more sample projects that contains the normal documents required for a Notes development project. Till now I haven't written any considerable documentation (shame on me, indeed)

Once I receive such a sample project, I would start with creating Word-templates for each type of document, as well as a draft project-plan (also hanging the documents as deliverables to milestone in project). That would become then the source of discussion with other developers.

Once there is more or less an agreement on the different steps involved (I think the following), we can start about thinking which tools to use to automate some of this erraneous work:

- Requirements Analysis (Document 1)
- Solution (Document 2)
- Development (Document 3)
- Testing (Document 4)



Document 1 (Requirements) :
Goal
Use Cases

Document 2 (Technical solution) :
Description forms
Description databases
Description interaction between different design-elements

Document 3 (Technical Documentation Application) :
based on document 2, since the application should be the implementation of the technical solution

Document 4 (Testing) :
Test Scenarios
Test Results ( also end-user testing)

Document 5 (Deployment) :
End-user help (or integrated in application)


So if anyone have some real documentation of a large project you once have done as a Lotus Notes specialist, which is not too confidential, please send it to me.
I would then distilise the necessary elements into a general action plan (with sample deliverables) for application development in Lotus Notes. This will be published on OpenNTF where I already defined a project , so other developers can discuss it, and we can further finetune it.

Here is the project "An IBM Lotus Domino Standard Way of Working database"
{ Link }

6 - We may have to agree to disagree. We have all experienced the inheritance of applications not coded to some some standard within an organization and spent wayyyy too much time trying to digest what is happening where, especially when the code has not been documented. Using common variable syntax aids in this situation.

Yes there needs to be a balance, but that balance requires some level of consistency. When using RAD, this becomes even more important. One of the key components of RAD is re-use of code assets. Without a consistent standard, this can be impaired.

You also said:

.."cur" is a NotesDocument and "x" is a collection, I'd reconsider hiring practices.

and of course I will have to disagree here as well. The idea is not that the code makes immediate sense to the the 'team' but not necessarily to someone inheriting the code.

If instilled as a best practice, there is no burden, undue or otherwise, on developers but gives them a common syntax to communicate so one person's cur is not a document and the other person's cur a currency string, especially when putting together modules coded by different people on a team.

And the bottom line: these are not ideas, but standards put out as part of ISO Standards, and are essential for an organization to meet the 'Definition' maturity level of the Software Capability Maturity Model (CMM).

7 - Alan,

I will take Matthias' post and take it a step further. Coding standards should be the same for for all projects in an organization, not set on a case by case basis.

There is an excellent article on coding standards in the View:

The Whys and Hows of Notes/Domino Development Standards

http://www.eview.com/eview/viewr5.nsf/21059a128be01bd98525653600120bea/c441fbabe59d2de285256a55007c9555?OpenDocument

From an internal control standpoint, you standardize because:

"To enhance the quality of programming activities and future maintanance capabilities, program coding standards should be applied. Pogram coding standards are essential to reading and understanding code, simply and clearly, without having to refer back to design specifications...The programming standards applied are an essential control, since they serve as a method of communicating among members of the program team and users during system development. Program coding standards minimize system development setbacks resulting from personnel turnover..."
Source: Information Systems Audit and Control Association

You said:

I have seen this in code, I never understood why. If you want the type in the variable name why not use the postfix characters $ for string and % for integer, # is double etc.

That is all well and good if you are limiting to these items, but what about Documentcollections, views, viewentrycollections, doc, etc.

For this reason, I usuall follow the following syntax:

string str
variant var
double dbl
integer i
NotesDatabase db
NotesView view
NotesDocumentCollection col
NotesViewEntryCollection vCol
DotesDocument doc
NotesItem item
NotesRichTextItem rtItem

etc etc.

There are many ways to skin this cat, but the bottom line is that the cat should be skinned and done so consistently across an enterprise.

8 - I agree with Christopher:
Maybe due to habit I use prefixes. Anyway, if I have to modify an application, it is very helpful for me if the programmer used standards (prefixes, option declare etc.).
Unfortunately, the templates provided with Notes/Domino do contain code where prefixes etc. have not been used. Only in some routines you can find str-prefixes etc.

Whenever I need to reuse a function or sub which someone else has coded without using standards, I use search&replace and set the appropriate prefixes.

In my opinion, it is a must have using prefixes, such as
str for String
i for Integer
doc for backend-doc (or docThis, docMail etc., if you process some other docs in the code)
item for Item
col for Notes Document Collection (or: ndc, collection)
view for view
uidoc for Frontend-Doc
etc.

Btw., constans should always be in capital letters.

Rocky also does not use standard prefixes in his book. Anyway, I think you should use 'em.

Just my opinion

Matthias

9 - Thanks Rocky, for your selfless use of your blogs and your time to help enrich the Lotus community. Thanks to everyone else for all of your helpful responses.

However, I have to apologize because I suppose I asked the wrong question or at least was not clear enough. As far as managing the development of the code and design, I've got that part handled fine. The part that has become a little overwhelming for me is the project management side of things. Meeting with users and turning their business problems into good solutions. So I guess what my real question should be is... What goes into to a good design specification and what is the best way to organize it? Are there an applications out there designed specifically for organizing desing specs for Lotus Notes Applications?

Thanks again,
Ryan

10 - There's no reason a prototyping cycle can't produce documentation. You just document it afterwards.

11 - Inherit, inherit, inherit. If you can accurately divide responsibility for design components, then you can cross-inherit from multiple templates to keep designers from stepping on each other. This is an incredibly powerful technique, that basically allows you to add a "compile" step to your template version builds (File - Database - Refresh Design).

It can also be extremely helpful to structure your NSFs into logical groups. For instance, you might have a production application which is set to inherit design from "TEST VERSION." Then your test version is set to inherit from "DEV VERSION". If your working on a server where the Design task doesn't run automatically (or you've got your versions on unique servers,) you can control when these updates take place by running the refresh manually.

12 - I know it costs, but TeamStudio is a wonderful product. There is only 3 of us that do Notes where I am and the other 2 work on the same application. They use the Ciao! product to check-in/check-out elements and also keep that all important history to roll back to just in case.

13 - Oh and something which I realized was so obvious I had not thought of it after someone showed it to me.

If you find you have an old design element (Page, view, form, agent, etc etc) that you want to keep but are not using and you are getting sick and tired of it sitting in the middle of all your design elements, rename it with a small "x" in front of the name and the alias, that way it will always show up at the bottom and be out of the way.

14 - And you would end up failing an external audit of your systems environment, sadly to say.

15 - And you would end up failing an external audit of your systems environment, sadly to say.

I'm confused by this statement. What do you mean?

16 - Actually I was not thinking in terms of audit habits, but the fact that an IS Auditor is looking for semblance of a development methodology of some kind and documentation to support what is being done. It has nothing to do with Quantity. If something or some process can be clearly documented in one parapgraph, awesome. It is the absence of any kind of documentation that drives auditors deeper.

Prototyping is an excellent tool to accelerate development as long as the risks associated with it are recognized and accounted for. And honestly, how many of us are really disciplined enough to go back in after the fact and document?

I would go into more here, but it would take up too much time and space. Look for the White Paper I am working on for a July release.

17 - Trent, excellent point. I should have made that clear. Come up with the best solution, some alternatives with pros/cons, and then let the client decide based on those recommendations. You can't go do what you think is "best" however, because it will come back to bite you.

Rock

18 - Good comments guys! I'm new to Notes development and
I've been told that my predecessor has been making design changes directly in the production environment.
Is there any way to properly resynch the databases and templates without loosing any design changes?

19 - 1. Gain an understanding of the organization, its culture, and its commitment to solid development practices.

2. Make sure there is ONE AND ONLY ONE Project Sponsor/Application Owner. Otherwise you will be floundering in conflicting requirements.

3. Identify, classify and prioritize the vulnerabilities and threats to develop an overall inherent and control risk assessment for the project. Use this assessment to build in application controls up front as it becomes more expensive to introduce controls after the fact. This should be done at the requirements definition phase.

4. Make sure a change management process and quality assurance process is in place. This will reduce scope creep.

5. As Rocky said: Communicate, Communicate and communicate. AND in case you forgot, Communicate again. AND do it in writing!

6. DOCUMENT EVERYTHING IN YOUR CODE!

7. Reuse standard code and assets. Take Karen's words above to heart. This falls under the need to segregate responsibilities to maintain effective internal controls.

and so on and so on...

20 - curious about this point

b) define standard prefixes for variables (e.g. strStuff for String, iStuff for Integer etc.) when starting a new project.

I have seen this in code, I never understood why. If you want the type in the variable name why not use the postfix characters $ for string and % for integer, # is double etc. this way the interpreter understands what you are talking about too and won't make them variants hence has a chance to give you an error on saving rather than a runtime error. Personally I tend to declare stuff explicitly and call a spade a spade, if a variable contains the cost of production of an item then I will call it CostOfProduction.

21 - Can we revive this thread? It seems more relevant than ever in 2006.

As more and more corporations hire auditing companies the days of gathering requirements on a napkin, bantering design ideas around the break room, and commenting code as you go just aren't cutting it anymore. We are now being held to a standard that requires every turn of the SDLC to be documented like a mainframe application. This is a practice abhorred by most of us RAD minded Notes jockeys, but something we are having to learn to live with.

I've been able to semi-effectively use the "generic" auditor friendly documents for requirements and testing. The requirements document format favored by auditors seems like Greek to most customers, but generally proves useful to design teams. The test documents are just painful to enumerate, but again generally somewhat useful in the end.

What has bothered me however is I’ve never found an auditor friendly design document template that works for Notes. Using an academic design template effectively removes all of the ingenious "lotus notes" concepts from your plan and leaves you with a bunch of over-normalized crap. What you get is something that serves to befuddle your Notes developers more than it servers to enlighten them. The cost is days of project resources on a tight deadline to write a bunch of useless @#% to pacify your SAS 70 auditor and pointy haired boss.

Has anyone come up with a design methodology to document Notes projects in a way that is useful to both developers and auditors???

22 - We are using the Teamstudio suite, especially Ciao. It is a great tool, that can be used to go "back in time" to get design elements that has been deleted, or changed. It also has built in "diff" support, so I can see what lines of code that has changed.
With bigger projects, it is usually a good thing to have a "common design"-database, with elements that are used throughout the server. That way, I only need to update the element i one place, and update the design of the databases. But that should be the first thing a Notes/Domino developer learns

23 - "Make sure that if you don't know the answer to a design question, you ask the client (or whomever should make the decision)."

I think the best way to handle this is to figure out the best solution, and then run it by the client. It's never a good idea to give a client open ended questions. My technique is usually, "I wasn't clear about this, but I propose we do XYZ. Does that sound good?"

24 - Interesting discussion.
Anyway - what IMHO is important in developing a N/D app: divide the development expediently.
Let e.g. modify programmer A scriptlib A, programmer B scriptlib B+C, programmer C all the forms etc.

Surely we have to backup everything. Who cares? In DVD era disc space costs are negligible (although we would never reach the DVD-disc space limits with simple N/D - development).

My suggestions for a app dev. project:
a) specification is required. Without a detail specification you should not start to develop.
b) define standard prefixes for variables (e.g. strStuff for String, iStuff for Integer etc.) when starting a new project.
c) Option Declare must be used
d) use/create ScriptLibs and classes whenever it makes sence (reusable code etc.)
e) comment the code (!)
f) communicate: have daily meetings with the developing-team. Exchange all necessary informations.
h) backup everything every time
i) Make sure your development team has the skill to develop applications
j) show the customer the results regularly. This prevents realizing things the customer does not want to have.

Just my humble experiences so far..

25 - She beat me to it. Although it's a trite name, it's a great product. IBM loved it so much they did a global license for all their Notes developers, the lucky dogs.

26 - I will 3rd the TeamStudio Ciao vote. I've used it on large and small projects, since it was just a wee beta product in the late 90s. I highly recommend it in any organization that does a lot of development. Saved my arse numerous times.

One nice thing CIAO does is force you to consider your development environment. Not only have I built development servers that will be used for testing, but I've built template servers that hold all the template versions. This makes versioning, securing and managing templates a lot easier. My developers can pick up builds/versions of templates from one place and my production servers inherit from the template server when I make the new versions available to them. Since it's a dedicated server I can strictly control the server access and prevent "rogue" developers from updating code that's already been versioned (you think it would never happen to you, but it does). All of this ensures that everyone is working with the same code base.

Another thing CIAO does is force you to consider different peoples roles in the development, versioning and template management process. I find that I end up with team leaders (build managers) and team doers (developers). This organization really helps with internal communication.