Preferred LotusScript comment style

As previously mentioned I’m looking into starting development of LotusScript.doc version 2 and for that I’m also rethinking how comments are written when writing LotusScript. In version 1 of LotusScript.doc I have only supported a LotusScript’ified version of the Javadoc syntax which meant that only the following comment syntax is considered valid:

'/**
' * This is my comment for the DoStuff sub-routine.
' */
Public Sub DoStuff()
   ...
End Sub

Comments of this kind can be placed inside or outside of code constructs (class, sub, function etc.) and will be picked up by LotusScript.doc accordingly. Apart from this you can write a description for a design element by using the lsdoc_description() sub-routine. This is the equivalent of the package.html from javadoc. Normally it would be used like this:

Private Sub lsdoc_description
%REM

%END REM
End Sub

For LotusScript.doc v. 2 I would like to make this more flexible and support multiple commenting schemes so I’m thinking:

  • “How do you comment your LotusScript?”
    • Do you comment using %REM sections?
    • Do you comment inside or outside the sub/function/class etc.?
    • How do you document the design element it self?

Also – one thing is how you do it now – another is how would like to document your code in the future.

I would really appreciate any input…

12 thoughts on “Preferred LotusScript comment style”

  1. Hi

    I currently comment all my code using a block of text after the header eg.

    function xxx (a as string) as boolean

    ‘!———————-!
    ‘! !
    ‘! Description: bla bla !
    ‘! Params: bla bal !
    ‘! !
    ‘!———————-!

    Like

  2. Hi Mikkel,

    we use the following style in classes:

    '/**
' * Class comment.
' */
Public Class XYZ

    '/**
    ' * Method comment.
    ' */
    Public Sub DoStuff()
    ...

    In “normal” functions and sub we comment inside:

    Public Sub DoStuff()
    '/**
    ' * Sub comment.
    ' */
    ...

    I personally do not like the
    Private Sub lsdoc_description()
    and would prefer a comment block in the Options section.

    Thomas
    http://www.assono.de/blog.nsf/

    Like

  3. Hi Mikkel,

    we are using the LSDoc style for commenting (for obvious reasons 🙂 ).
    However we used to use %rem as it is much more convenient, e. g. when inserting additional lines in a comment (as we have no Eclipse inserting the javadoc syntax automatically).
    I’d prefer to comment inside functions/subs (currently supported) and classes/methods (currently not supported). It helps for copy and paste operations.

    I also would prefer the comment block in the Options sections as stated above (I do not like the lsdoc_description, which is easily overlooked when a human being is reading the code 😉 ).
    Hans-Peter

    Like

  4. Well, Mikkel, I’m sort of a hack coder, and I like to place a quick overall description of the code at the beginning, functions/subs/classes and script libraries –how they fit together. Then I comment in the code.

    Like

  6. Hi Mikkel,
    I would prefer the LSDoc comment to be inside a methode.

    Public Class XYZ
'/**
' * Class comment.
' */

    Public Sub DoStuff()
    '/**
    ' * Method comment.
    ' */
    ...

    This is mainly because I use LSClassBuddy / NotesHound Class Navigator to navigate inside the classes and they jump just to the start of the method. With the current comment style (comments outside of the method) I have to scroll up again to see the LSDoc comment.

    First I thought about using a comment style using %REM lsdoc.But with %REM there is no way to indent the comment for methods. Which would make it harder to read.

    Public Class XYZ
%REM lsdoc
Class comment.
%END REM

    Public Sub DoStuff()
%REM lsdoc
Method comment.
%END REM
    ...

    Like

  7. Hi MIkkel!
    Comments inside the classes and subs would be best like Bernd wrote. It’s the best way when you cut’n paste them between scriptlibraries. Also it would be great to use %REM instead of ‘

    Like

  8. Ideas:
    1. 

    %REM lsdoc
@param foo Integer
%END REM

    Anything that you type after the REM is part of the comment. So, if you put “lsdoc” after it, it can denote that this particular comment is in lsdoc format, and should be processed. You could also use “%REM lsdoc_description” for that particular block, so that people can put it wherever they feel comfortable.

    2. 

    ''
'@author Brian
'@param blap Integer

    or

    ''
'@author Brian
'@param blap Integer
''

    This is less typeheavy than the apos-plus-javadoc format, and it’s a bit more intuitive for me. You can end with either the next ” that you run into, or the first non-comment line.

    Like

  9. I’m a little late to the party, but I wanted to throw in my 2 cents.

    I’m ok with the current (v1) syntax.  The only thing I don’t like about it is the use of the lsdoc_description() sub.  I would much rather place the library description in the Options module.

    Like

  10. Hi Mikkel,

    I am currently setting up lsdoc and bumped into a question that I hope you could help me with.

    When adding a database to the lotusscript.doc configuration database and running the build; all design elements are visible in the html-documentation except for agents and script libraries built in Java. Maybe this is true for simple action agents and formula agents as well, haven’t checked.

    What I wonder first is if I missed some adjustment and if not I think it would be nice to list all design elements despite that lsdoc won’t work for them. It would be great to at least be able to give a short overall description for them or else you need another way to comment and maintain the documentation for these design elements.

    Thanks for a great tool!

    Like

  11. In version 1 LotusScript.doc will only include agents and script libraries with LotusScript. In the upcoming version 2 you can add design elements from other languages although the contents wont be parsed. Hope that clarifies it.

    Like

  12. In the release 2, if it is possible to implement @see parameter to understand the subroutines/function linking within the script library/across script library without the need for implementing them as classes, that will be really helpful as we have our code implemented without any classes.  As of now, we are not able to make @see in one function to be linked to another in the same script library or any other script library.

    Like

Comments are closed.