• Commenting code

    Home » Forums » AskWoody support » Productivity software by function » Visual Basic for Applications » Commenting code

    Author
    Topic
    WSShane Sargent
    AskWoody Lounger
    March 29, 2001 at 9:34 pm #354477

    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)

    Reply | Quote
    Viewing 2 reply threads
    Author
    Replies
    • WScharlotte
      AskWoody Lounger
      March 30, 2001 at 4:30 am #520902

      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:

      If MyCondition=True Then
  ...
End If 'MyCondition=True
      Reply | Quote
    • WSchrisgreaves
      AskWoody Lounger
      March 30, 2001 at 11:27 am #520942

      I place this immediately after the decalartion PUBLIC FUNCTION

      ' 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.

      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

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

      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.

      Reply | Quote
    • WSVBNerd
      AskWoody Lounger
      April 9, 2001 at 6:11 pm #522147

      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.

      Reply | Quote
    Viewing 2 reply threads
    Reply To: Commenting code

    You can use BBCodes to format your content.
    Your account can't use all available BBCodes, they will be stripped before saving.

    Your information:




DON'T MISS OUT!
Subscribe to the Free Newsletter
We promise not to spam you. Unsubscribe at any time.
Invalid email address

View the Forum

  • Recent Replies
  • My Replies
  • My Active Topics
  • New Posts in the Last day
  • Private Messages
  • Knowledge Base
  • How to use the Forums
  • All Forums

    • Recent Topics

    My Profile

    March 2025
    S M T W T F S
     1
    2345678
    9101112131415
    16171819202122
    23242526272829
    3031  

    Remembering Woody

     

    Want to Advertise in the free newsletter? How about a gift subscription in honor of a birthday? Send an email to sb@askwoody.com to ask how.

    Mastodon profile for DefConPatch
    Mastodon profile for AskWoody

     

    Home • About • FAQ • Posts & Privacy • Forums • My Account
    Register • Free Newsletter • Plus Membership • Gift Certificates • MS-DEFCON Alerts

    Copyright ©2004-2025 by AskWoody Tech LLC. All Rights Reserved.