Documentation lotusscript code

Attribute(s)

  • Documentation - Code

    Description

    All LotusScript code must be properly documented. The required code documentation standards are described in the Details field.

    Motivation

    Properly documented code is a pre-requisite for an easy to support application.

    Example / Details

    Script code must be thoroughly documented to allow for an easy determination as to what each section of script does.
    The apostrophe ( ' ) is used to designate code as being remarks or documentation. The color of the remarks placed after the apostrophe will be in green (by default).
    The documentation can be placed on a separate line or on the same line as a line of code (to the right of the code).
    The latter should e.g. be used to indicate the name of the Script Library when calling a subroutine from a script library.

    Try to explain the functionality of the script and not what technical is happen.
    Incorrect:
    Messagebox doc.FirstName(0) 'Displays the content of the field FirstName in the document DOC

    Describe why you are wrote this code, the functionality.
    Correct:
    Messagebox doc.FirstName(0) 'Displays the firstname of the person document, so the user can check if this name.


    The following information should be included by each module of script code:

  • The purpose of the script
  • The original programmer
  • The date the code was completed
  • The date of change
  • The author of the change
  • A short description of the change
  • A version number for the code

    It is also possible to communicate to users what a section of script is doing, particularly if the user is expected to wait while the script is running. The 'Print' command can be used for this purpose.

    At the top of each module of script:

    %REM

  • **********************************************
    Purpose: <Description of function, sub routine, agent or script library>
    Original Author: <Author Name>
    Creation Date: <dd-mm-yyyy>
  • **********************************************
    Change Overview:
    Date Programmer Modification
  • **********************************************
    <dd-mm-yyyy> <Programmer> <Description of Modification>

  • **********************************************
    %END REM

    Examples:
    %REM

  • **********************************************
    Purpose: Open a NotesDabase by a standard reference key
    Value : Array of sepecified keywords
    Original Author: Bas Peters /Marc van Helvoort
    Creation Date: 29-03-2000
  • **********************************************
    Change Overview:
    Date Programmer Description of Change
  • **********************************************


  • **********************************************
    %END REM


    Documenting within the function or subroutine

    call ImportFiles(filename) ' Subroutine of Script Library Import, import the new person data.
    Messagebox doc.FirstName(0) ' Displays the firstname of the person document, so the user can check if this name.

    Using Print Statements:

    Dim UIWS as New NotesUIWorkspace
    Dim......
    Dim....

    '***********************************************
    '***Create Report***
    '***********************************************
    Print 'Report is being created'
    If ......... then


    •  25 May 2008  08:18:50 PM CEDT  Atos Origin moderator/NotesOSS

     |  |  | | | documentation