Results 1 to 5 of 5

Thread: Commenting code

  1. #1
    3 Star Lounger
    Join Date
    Mar 2001
    Location
    Minneapolis, Minnesota, USA
    Posts
    262
    Thanks
    0
    Thanked 0 Times in 0 Posts

    Commenting code

    I'm trying to do a better job of commenting my code (mostly VBA functions). I'm wondering what other developers find useful when looking through code written by another. In addition to commenting individual lines of code that aren't blatantly obvious to someone of moderate abilities, I've settled on the following bits of info thus far for each function, but am looking for general feedback and suggestions: have I missed anything useful, duplicated, etc. Thanks in advance for your 2-cents!

    Purported Function:
    Requires:
    Returns:
    Known abnormalities:
    Created: (by whom and when)
    Edited: (by whom and when)
    <font face="Comic Sans MS"><font color=blue>~Shane</font color=blue></font face=comic>

  2. #2
    Plutonium Lounger
    Join Date
    Dec 2000
    Location
    Sacramento, California, USA
    Posts
    16,775
    Thanks
    0
    Thanked 1 Time in 1 Post

    Re: Commenting code

    Actually, I find it most useful when lots of comments are included in the code itself, even on things that may seem obvious at the time, and especially on each declared variable to indicate what it is for. Going back later, even to my own code, I often find that things that seemed obvious at the time are less so when I haven't looked at them for months.

    One thing I find especially helpful is to copy the determinant expression of each structure and paste it as a comment at the end of the structure--makes it much easier to tell which End If matches up to a particular If Then when you have something like this:

    <pre>If MyCondition=True Then
    ...
    End If 'MyCondition=True</pre>

    Charlotte

  3. #3
    Platinum Lounger
    Join Date
    Feb 2001
    Location
    Yilgarn region of Toronto, Ontario
    Posts
    5,453
    Thanks
    0
    Thanked 0 Times in 0 Posts

    Re: Commenting code

    I place this immediately after the decalartion PUBLIC FUNCTION

    <pre>' Procedure : boolBookmarkExists
    ' Description: Test for existence of a bookmark
    ' Copyright: Chris Greaves Inc.
    ' Inputs: A document name, a bookmark name..
    ' Returns: TRUE if the supplied bookmark is in the existing document.
    ' Assumes: None.
    ' Side Effects: None.
    ' Tested: By the calls shown below.
    </pre>


    I found this layout somewhere when I had no standard, and adopted it as my standard, on the grounds that using someone-elses's standard was better than developing my own.


    I place this immediately before the END FUNCTION

    <pre>'Private Sub TESTboolBookmarkExists()
    ' MsgBox boolBookmarkExists(strPath & "emsref.doc", "BrokerEmail")
    ' MsgBox boolBookmarkExists(strPath & "emsref.doc", "BrokerSites")
    ' MsgBox boolBookmarkExists("z:emsemsref.doc", "BrokerWSites")
    'End Sub
    </pre>


    If I need to modify a function (always a risky business in a utility library) I drag the commented test outside the function and de-comment it. I run the text BEFORE making the chnage to verify the expected results. I make the change then run the test again. I might add more tests based on the changes to the function. Finally I drag the commented test back into the function.

    The TEST functions provide much help to me when I'm returning to an old friend, "Now how in Blazes does THIS work?", I ask, after which I single-step execution to find out.


    One of the best books I EVER read on documenting code was about fifty pages total, of which about 25 were cartoon illustrations "The Little Book Of BASIC Style", written for BASIC about 20 years ago, but relevant for all languages.

  4. #4
    3 Star Lounger
    Join Date
    Mar 2001
    Location
    Minneapolis, Minnesota, USA
    Posts
    262
    Thanks
    0
    Thanked 0 Times in 0 Posts

    Re: Commenting code

    Thanks to you both for your input!
    <font face="Comic Sans MS"><font color=blue>~Shane</font color=blue></font face=comic>

  5. #5
    2 Star Lounger
    Join Date
    Feb 2001
    Posts
    141
    Thanks
    0
    Thanked 0 Times in 0 Posts

    Re: Commenting code

    As I put in a earlier post about coding standards...

    When commenting your code, put less on what your code is doing and more on WHY you're doing it.

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •