PreviousNext…

Starting with Lotusscript (Part 2)

Introduction

This document, together with live application development using Lotusscript, is intended to assist the experienced Lotus Notes developer in starting to work with Lotusscript. In Part 2, a short article, we're going to take a look at documentation: what you should provide, what's "overkill," and a suggested format (each to their own though!)

Why document your code?

If your Lotusscript is more than around 10 - 15 lines in length, you might want to think about documenting it to some degree. OK, so one benefit is for other developers — perhaps the poor soul who will inherit your code one day — but there's also a benefit for you. I've coded complex script libraries with upwards of twenty sub-routines and / or functions, and it's great to have a memory-jogger in the form of documentation: Why did I use a NotesView object here, why not a NotesDocumentCollection? If I change this routine, what are the implications elsewhere in my application?

You get the idea. As we know, Notes allows us to wallop code here, there and everywhere. I've already discussed keeping one's code as central as possible, but of course there are times when we will have code that is inter-linked. It's useful to know about all dependencies ahead of making potentially disastrous changes.

What to document?

I've seen documentation that's longer than the code itself. I've also been guilty of that — easy trap to fall into. The key is to find your groove, and document code to a level that is useful for the developer without being arduous. To this end I've found that unless I'm writing code for a junior developer to learn from, I do very little "in-line" narrative. Well-written code should be pretty much self-explanatory. I shouldn't have to say that I'm "initialising all objects and variables" — that should be obvious.

Where the odd line may be useful is to explain a particular decision. For example, you're using the NotesDatabase.FTSearch method rather than NotesDatabase.Search to derive a NotesDocumentCollection object, because you need a sorted collection. In such a scenario, a wee comment to make that clear would be useful.

Other details

Other things one should include: who authored a piece of code; some kind of maintenance history; dependencies. These are all "must-haves" for any reasonably complex program. In addition, if I'm doing something a little out of the ordinary for some people (e.g. Win32 or Notes C API calls), then I may include an example of how the external function I'm calling is invoked. I would also suggest a brief overview of what your code does.

One example format

Each to their own. I often format code narrative like this (apologies if the wrapping is weird in your browser… but you get the idea!):

%REM
////////////////////////////////////////////////////////////////////
PROJECT: PROJECT NAME HERE
TITLE:   agRemoveAllFromFolder
PURPOSE: Removes all documents from the current folder.
CREATED: Ben Poole - 29 Jan 2001
PARAMS:  All messages & the error handler stored in "libStrings"
RETURNS: -
CALLS:   sub ErrHandler in libStrings
INVOKED: -
CHANGES: Ben Poole - 23 Jul 01 - updated error handler for UI errors
         Ben Poole - 14 Aug 01 - reverted to NotesViewEntryCollection,
         as we now populate the folder WITHOUT using a response
         hierarchy, which was causing the various 4005 error issues.
TESTING: Notes 5.05, Windows 2000 Professional
////////////////////////////////////////////////////////////////////
%ENDREM

Further reading

Comments on this post are now closed.

About

I’m a software architect / developer / general IT wrangler specialising in web, mobile web and middleware using things like node.js, Java, C#, PHP, HTML5 and more.

Best described as a simpleton, but kindly. You can read more here.

";