Documenting Your LotusScript Classes

Just a quick LotusScript tip:

Hopefully you've been inspired by my recent adventures in creating custom LotusScript classes. If so, you'll have noticed that, when creating your own properties and methods in these classes that they get their own comments added in.

For example, if you type "property get foo as string" and then press return, you'll see something like this:

        Property Get Foo
        Description: Comments for Property Get
Property Get Foo As String

End Property

Domino Design auto-adds the comments above the property for you.

It's easy to see this as an annoyance and find yourself taking the comments out to keep your code tidy. However, I've forced myself to stop doing that and now make a point of adding in a meaningful comment. Like so:

%REM Property Get Action Description: Value of the "Action" field, which is used by the workflow associated with most documents Value is only available when editing/saving (not stored on document)! %END REM Property Get Action As String Action = GetFieldValue("Action") End Property

The benefit of doing so is manifold. Not only does it remind yourself what your intentions were but also, more importantly, future maintainers of the code.

But the real tip here is that, if you comment code using the standard way then, when you hover the mouse over a call to that property in use in your code you get to see the "documentation" inline. As below:


That alone makes it worth the time to document properly. Even if just for your own benefit as a quick reminder of what everything is.


    • avatar
    • amadia
    • Wed 27 Mar 2013 12:09 PM

    Hi Jake,

    A very useful and interesting !

    (As usual)


    • avatar
    • axel
    • Wed 27 Mar 2013 02:44 PM

    but please, please only when necesary and with your brain turned on.

    Intention, etc. for the really not that obvious stuff.

    In java land there is that amusing, static code-metrics driven behaviour to let the ide generate comments like


    * this method returns the foo property.

    * @return .


    boolean getFoo() {

    return foo;


    all over the sources.

    In bigger projects often the task for a poor guy who is considered to be lacking skills, focus capabilities, etc. for any endeavour more challenging.

    • avatar
    • harkpabst_meliantrop
    • Wed 27 Mar 2013 05:55 PM

    Hi Axel, still following codestore?

    Frankly, I don't quite get, what exactly the task for the dumb guy would be (Deleting obsolete comments? Adding them, where the IDE didn't do it?), but I can't think of any public property of any class, that wouldn't be worth at least a short comment ...

    I just had hoped, that IBM would have adopted Mikkel Heisterberg's LSdoc project. Having said that, it might be worth noting, that the LS editor's pop up help is not restricted to comments using the %REM ... %END REM notation. If you have existing LSdoc style comments in your classes, you will notice, that those are displayed as well.

      • avatar
      • axel
      • Thu 28 Mar 2013 04:57 AM

      Hi Fabian,

      I even comment on atnotes and have visited uklug last year. I haven't opened a Notes Client for 2 years and my last line of code should date 3 or 4 years back.

      Nostalgia. Don't know. Probably the awsome work environment back than at Kasten ;-)

      And yes, there are lots of pointless comments, at least on the projects I participate. Architects and Project Managers love to activate checkstyle rules for comments and programmers love to find ways to trick this rule with the least amount of effort.

      Writing good comments is hard. I am only theoretically good at that. Just at this very moment I don't understand part of some strange stuff in some jsf beans, I have written 2 month ago.

      We need comments in the not obvious parts of the program. I tend to write these late in the day in an empty office. In the process I change a lot, so I don't see much point to write comments as there is a high probability that I will delete this source code. I should write comments when this for me hard part stabilizes, but I often tend to "forget".

      Thou shall write comments is an ok guideline, but what we really need are good comments and this is hard.

    1. I love lsdoc.org!

      I have these comment templates that automatically make lsdoc-compatible stubs to my classes, subs and functions.

      The real killer application for lsdoc.org is that I have a system documentation which is available with very little effort. Whenever a client says 'what about the documentation', I print out the HTML files relating to the project databases, and I am a hero.

      The Lsdoc.org makes clickable documentation files, and I find makes a very nice display of the way different classes link to each other.

      Here are my snippets:



      ' * A Class to represent

      ' * @author ${author}

      ' * @version ${date}

      ' *************************************************************************************/



      ' * ${element_type} ${element_name}

      ' * @param

      ' * @return ${element_returntype}

      ' * @author ${author}

      ' * @version ${date}

      ' *************************************************************************************/



      ' * ${element_type} ${element_name}

      ' * @param

      ' * @author ${author}

      ' * @version ${date}

      ' *************************************************************************************/

  1. Pro Tip: The comments in LotusScript accepts HTML so you can make them really shine when hovering! Bold, Red, Tables, Images... :)

      • avatar
      • Jake Howlett
      • Thu 28 Mar 2013 02:52 AM


Your Comments


About This Page

Written by Jake Howlett on Wed 27 Mar 2013

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content