Welcome to the third part of this series of articles about how to write better code for the Notes/Domino platform. In part 1 I wrote about creating your forms in a way so you get an instant idea of how they work (what is hidden, computed-for-display fields, etc) and in part 2 the subject had moved to Lotusscript, more specifically variable names and comments.

As already mentioned in that last article (as well as in some of the comments), breaking out code into functions is a great way to make code easier to read as well as dramatically easier to maintain. That is what I will focus on in this article.

Functions

In Lotusscript, the functions are declared the same way as in Visual Basic:

Function YourFunctionName(argument As DataType) As ReturnDataType
    YourFunctionName = ReturnValue
End Function

You can have any number of arguments, from none to many. However, it is often suggested to keep the number of arguments to a minimum. I try to not use more than three arguments, unless there is no way around it. If you need to send a lot of information into a function, use an array or a custom data type instead. Then it is easier to change the arguments later, without changing the signature of the function. I have occasionally seen that cause issues in nested script libraries. Also, with many arguments the function declaration will probably not fit on your screen, unless you wrap the line. I try to always keep code visible in the editor, as it is easy to miss things when you have to scroll sideways to view code.

So let’s take a look at one of the code samples in my last article, the one where we call names.nsf to get the email address for the current user. Let’s make this a function (like Kenneth Axi suggests in his comment), but we will make it a more generic function, returning the email address for any user present in address book, not just current user.

Here is the original code:

key = session.CommonUsername
Set view = db.GetView("People")
Set doc = view.GetDocumentByKey(key)
emailaddress = doc.GetItemValue("InternetAddress")

Below is how I would write the function. We will talk more about error handling later, but you want to make sure to always check return values before you use them. The function takes one argument, the name of the user we want the email address for, and returns the email address, or blank if no user/address was found. The username must be in the same format as the names are being displayed in the view we doing the lookup in.

Function getEmailAddress(username As String) As String
    Dim personname As NotesName 
    Dim nabdb As NotesDatabase
    Dim nabview As NotesView
    Dim persondoc As NotesDocument

    If username = "" Then
        MsgBox "Username is empty. Exiting.",,"No Value"
        Exit Function
    End If
    '*** Create NotesName object and get CommonName part.
    '*** We do this so username argument can be in any format.
    Set personname = New NotesName(username)

    '*** Use Domino Directory on main server
    Set nabdb = New NotesDatabase("Domino1/MyDomain","names.nsf")
    If nabdb Is Nothing Then
        MsgBox "Could not open names.nsf. Exiting.",,"Error"
        Exit Function
    End If

    Set nabview = nabdb.GetView("PeopleByFirstName")
    If nabview Is Nothing Then
        MsgBox "Could not find view 'PeopleByFirstName'. Exiting.",,"Error"
        Exit Function
    End If

    Set persondoc = nabview.GetDocumentByKey(personname.Common)
    If persondoc Is Nothing Then	
        getEmailAddress = ""	  ' Did not find person, return blank value
    End If
    getEmailAddress = persondoc.GetItemValue("InternetAddress")(0)
End Function

You may wonder why I am creating a NotesName object and not just using the name passed as argument directly? That will allow me to get the Common Name of the name, no matter in what format it is passed. You should always check the values of any arguments passed to your functions to make sure you can handle them and that they contain valid data. In this case I make sure the username is not empty, but for a string containing a date I would use the IsDate() function to test that the value is a valid date-time.

Now we can call the function like this:

MsgBox getEmailAddress("Karl-Henry Martinsson")
MsgBox getEmailAddress("Karl-Henry Martinsson/MyDomain")
MsgBox getEmailAddress("CN=Karl-Henry Martinsson/O=MyDomain")

Beautiful, isn’t it?

How to name functions

This brings us to the naming convention for functions. For functions, I use CamelCase, as that makes it much easier to see what the function does. I have to admit, I am not always consistent with get and set, I sometimes capitalize the first letter, sometimes not. Using CamelCase for functions and lowercase for variables makes it easier for me to read my code later, but you should do what you are comfortable with, and what works for you.

The actual name of the function should describe what it does, without being too long or too short. A well named function will by itself document what it does when you see it in your code later. The function we just created above could have been called getEmail() or getEmailAddressForUserFromCentralServer(). The first is a little too short — you don’t know if it is getting a mail address or an actual email document– while the second is too long.

Script Libraries

Consider creating script libraries where you store commonly used functions. I have a number of script libraries, containing different sets of functions, and when I need certain functionality in a new application, I just copy one or more of them into that application. I name the script library in a way so I know what functions are in each one of them:

I group functions into separate script libraries, making it easy to copy just certain functionality to a new application.

There are many ways to name your script libraries, and I know some developers who use very complicated elaborate naming systems, where they can see at a glance if the script library uses back-end or front-end functions/classes, etc. I prefer a slightly simpler approach.

So let’s look at a real life code example, from one of my production applications. This is an agent, called from a browser, that generates some charts and other information, based on the URL parameters passed to the agent.

Thanks to the descriptive function names, hardly any comments are needed. The only comment in this code segment clarifies why we are doing what we do. Obviously the code is much more complex than what you see above, but it will give you an idea of how you can make your code easy to review and maintain.

In the next article I will talk about classes and object oriented Lotusscript.

We already talked about how to make your forms and views easier to maintain. But in most Notes/Domino applications, a majority of the code is written in Lotusscript (at least for traditional applications, XPages are outside the scope of this discussion for now).

It is not hard to write easy to read Lotusscript code. Just follow some simple rules. As always, there are more than one way to do things, but this is how I do it (most of the time). I found that this works for me.

Variables

• Always use Option Declare (or Option Explicit) in all your code. This will prevent you from getting errors later when (not if!) you spell a variable wrong. Option Declare forces you to declare all variables before you use them. It also helps you by warning if a function or method is called with a variable of the wrong data type. Most of your bugs can be avoided using Option Declare. Use it!
• Give your variables meaningful names. There is no need to abbreviate variables and/or give them cryptical names, or  you will just spell them wrong later. Use a naming system that makes sense to you. As I mentioned in my previous post, I avoid Hungarian notation, it just makes the variables hard to read. Since Lotusscript is a strongly typed language, the compiler is taking care of data types. I however do use some indicators for certain variables. For the few global variables I use, I do prefix them with g_, as I then can give local variables a similar name. By giving your variables meaningful names, the code also becomes largely self-documenting.
• Be consistent in how you capitalize your variables. I normally write all variables in lower case only, but that is my personal preference. That way they are easy to distinguish from built-in Lotusscript functions and properties of objects. Some programmers prefer some version of CamelCase, which is fine. I occasionally use that, especially in Javascript.
• Be consistent in how you name related variables. If you have a variable named startpos to indicate the beginning position of a string within another string, name the other variable endpos, not posend. Think through all variables you need so you give them good names. The variables posstart and posend are not as easy to read and understand as startpos and endpos. Of course, using CamelCase, posStart and posEnd are much easier to decypher.
• Use the same/similar naming convention for the Domino objects as IBM uses in the online help. Use ws, uidoc, session, db, doc, etc. If you need more than one object of any type, e.g. NotesDatabase, name them in a consistent way. I always use thisdb for the database the code is executing in, nabdb for names.nsf, archivedb for (you guessed it!) an archive database, etc.
• Declare the variables at the beginning of the code/subroutine/function. Don’t declare them throughout the code, this makes it much harder to find them later, when you perhaps need to see what data type they are.
• Declare the variables in a logical order. I always group the variables by type. First the UI classes, then backend classes, then any custom classes/data types, and finally other variables. Within each group, I declare them in the order I am using them. The benefit of this is that you get an idea of where to look for the variables in your function/subroutine.
• Use Option Declare. Yes, this needs to be repeated. Way too many (especially new) programmers forget this, or don’t know about this.

Here is a typical example of how I would declare variables in one of my applications:

Dim ws As New NotesUIWorkspace
Dim uidoc As NotesUIDocument
Dim session As New NotesSession
Dim thisdb As NotesDatabase
Dim nabdb As NotesDatabase
Dim nabview As NotesView
Dim persondoc As NotesDocument
Dim doc As NotesDocument
Dim username As String
Dim phonenumber As String
Dim employeenumber As Integer

As you can see, this function will do some kind of lookup in names.nsf and retrieve the name, phone number and employee number from the person document. It is then (probably) storing the values into the backend document of the currently open document. Just by declaring and naming variables in a logical way you can often figure out what the code will do further down.

If you declare variables that you end up not using, remove them. Since you now are a good programmer who is using Option Declare, you can very easily test if a variable is used by commenting it out. If you don’t get an error, you can remove it.

Comments

This brings us to the art of commenting. Yes, it is a little bit of an art, and I have seen way too much code written where the code is either overly commented (not very common), or hardly at all (very common). The art is to add just the right amount of comments.

There is an old saying among programmers: “if the code was hard to write, it should be hard to read”. But it may not be another programmer that have to look at the code and find a bug in it or update it with new functionality, it may very well be you. And if you have commented your code, you will not have to analyze every line of code, trying to figure out hwo you were thinking a few months or even years ago.

You want the comments to explay “why”, not “what” the goal of the code, not explain the individual lines of code. What I mean with that is that it does not make sense to have code like this:

'*** Set key variable to current user's name
key = session.CommonUsername
'*** Get the "People" view in database
Set view = db.GetView("People")
'*** Get person document in view based on key
Set doc = view.GetDocumentByKey(key)
'*** Get the email address from the field "InternetAddress"
emailaddress = doc.GetItemValue("InternetAddress")

The comments in the example above does not add anything to the code. This code below is much better, and also shorter:

'*** Get email address for current user from person document
key = session.CommonUsername
Set view = db.GetView("People")
Set doc = view.GetDocumentByKey(key)
emailaddress = doc.GetItemValue("InternetAddress")

This comment explains what we actually are attempting to do. In real life, you would probably break out this code into a separate function with a descriptive name. The example above is just for illustrative purposes. I will cover functions in a future article.

Comments are crucial when you use some kind of work-around, or when your variables or field names have been named something that is not clear. I have cases where a field was initially named for the data it would hold, but later it was changed to something totally different. Make a note of that in your code. Or if you have to use some more or less obscure work-around to get the code to work, it would be very annoying if you (or another programmer) later removes that line. A typical example is to perform a db.FTSearch() with a query that will not return anything to get an empty document collection for later use.

I use the following system for comments:

• Comments explaining one line of code or a command are put on the same line, with no stars, just an apostrophe.
• Comments explaining a section of code are put on their own line, and I start them with three stars to make them more visible and make it clear they are comments and not code.

Remember, comments are there to help you remember (or tell someone else) what is happening in the code.

Bringing it together

Let’s look at a real life example. This one is taken from one of the IBM developerWorks forums, where a user had some issues attaching files to a rich text field. After getting some help, he posted the code he finally got to work:

Sub Initialize
    Dim s As New NotesSession
    Dim ws As New NotesUIWorkspace
    Dim uidoc As NotesUIDocument 
    Dim filesys As String
    Dim FullPath As String
    Dim OUName As String
    Dim FileName As String
    Dim Path As string
    Dim db As NotesDatabase
    Dim view As NotesView
    Dim doc As NotesDocument
    Dim Object As NotesEmbeddedObject
    Dim IDFile As string

    Set uidoc = ws.CurrentDocument
    OUName = uidoc.FieldGetText( "OUName" )
    FileName = uidoc.FieldGetText( "FileName" )
    IDFile = uidoc.FieldGetText( "IDFile" )

    Set doc = uidoc.document
    Call uidoc.Save 
    Dim FullPath1 As Variant
    FullPath = doc.GetItemValue("FullPath")(0)
    Dim rtitem As New NotesRichTextItem (doc, "FileName")
    Set Object = rtitem.EmbedObject(EMBED_ATTACHMENT,"",IDFile,OUName)
    Call doc.Save(True,True)
End Sub

As you can see, variables are declared all over the place, some declared but never used, inconsistent named, and of course no comments.
Here is my cleaned up version of the same code, with comments added as well:

Sub Initialize
    Dim ws As New NotesUIWorkspace
    Dim uidoc As NotesUIDocument
    Dim doc As NotesDocument
    Dim rtitem As NotesRichTextItem 
    Dim filepath As String
    Dim filename As String

    '*** Save currenly open document
    Set uidoc = ws.CurrentDocument
    Call uidoc.Save   ' Save UI doc so backend doc get updated

    '*** Get updated backend document and read field values
    Set doc = uidoc.document
    filepath = doc.GetItemValue("FullPath")(0) ' Path must end with /
    filename = doc.GetItemValue("FileName")(0)

    '*** Create a new rich text field called 'Attachment' and save doc
    '*** Use GetFirstItem() if the field already exists in document
    Set rtitem = New NotesRichTextItem(doc, "Attachment")
    Call rtitem.EmbedObject(EMBED_ATTACHMENT,"", filepath + filename)
    Call doc.Save(True,True)

End Sub

I think this code is much easier to follow, cleaner and easier to maintain. This is the kind of code I would like to see if I came in to update or modify an existing Notes application. Wouldn’t you?

Update: Made some small changes and clarifications, and fixed some typos.