Comments please

**GlenW** · Mar 27th, 2002, 04:35 AM

I have to write a lot of methods, that are going to be used by people after I have moved.
What I want is a consistent style particularly for commenting and layout.
Would anybody care to read thro' this example and comment on my current 'style'.
Any comments would be greatly appreciated.
The person taking over from me may not have much experience so do you think this example would be easy to understand and use.
Any comments on the actual working of the Sub would also be appreciated.

VB Code:

'---------------------------------------------------------------------------------------
' Procedure      : FillFlexGrid
' DateTime       : 26/03/02 08:40
' Author         : Glen [email][email protected][/email]
' Purpose        : Fills MSFlexGrid with values in ADODB.Recordset
'                  If NewGrid is set to false inRes values are added
'                  to existing rows
'                  Else old rows are deleted
' Pre-Conditions : inGrid must have 1 or 0 FixedColumns
'                  inGrid must have 1 or 0 FixedRows
'---------------------------------------------------------------------------------------
'
Public Sub FillFlexGrid(ByRef inGrid As MSFlexGrid, _
                        ByVal inRes As ADODB.Recordset, _
               Optional ByVal NewGrid As Boolean = True)
    
    'If a new grid remove old rows
    'If NewGrid
    If (NewGrid) Then
        'If inGrid has a fixed row
        If (inGrid.FixedRows = 1) Then
            'Leave FixedRow
            inGrid.Rows = 1
        Else
            'Clear all rows
            inGrid.Rows = 0
        End If ' (inGrid.FixedRows = 1) Then
    End If ' (NewGrid)
    
    'Make inGrid columns = number of fields in inRes
    inGrid.Cols = inRes.Fields.Count
    
    Dim thisRow As String   'To create row to add to grid
    Dim i As Integer        'For loop count
    
    'If there are records
    If (Not (inRes.BOF And inRes.EOF)) Then
        'Go to the first one
        inRes.MoveFirst
        'While not at the last one
        While (Not inRes.EOF)
            'If inGrid has a fixed column
            If (inGrid.FixedCols = 1) Then
                'Make 1st value TAB
                thisRow = vbTab
            End If ' (inGrid.FixedCols = 1) Then
            'While fields left
            For i = 0 To inRes.Fields.Count - 1
                'Add field value to thisRow & TAB to move to next Column
                thisRow = thisRow & inRes.Fields(i).Value & vbTab
            'Next field
            Next ' For i = 0 To inRes.Fields.Count - 1
            'Add thisRow to inGrid
            inGrid.AddItem thisRow
            'Reset
            i = 0
            'Reset
            thisRow = ""
            'Next record
            inRes.MoveNext
        Wend ' (Not inRes.EOF)
    End If ' (Not (inRes.BOF And inRes.EOF)) Then
    
End Sub ' FillFlexGrid

**cafeenman** · Mar 27th, 2002, 04:42 AM

Regarding the comment lines only:

I personally like minimum comments to explain confusing or not so obvious parts of code. Reading your code, a lot of the comments aren't necessary.

But I also know that some companies want you to comment every single line. So it probably isn't a bad habit. When I copy code, I usually delete most of the comments from code where I understand what's going on. Otherwise I leave them.

**GlenW** · Mar 27th, 2002, 04:45 AM

Originally posted by cafeenman
Regarding the comment lines only:

I personally like minimum comments to explain confusing or not so obvious parts of code. Reading your code, a lot of the comments aren't necessary.

But I also know that some companies want you to comment every single line. So it probably isn't a bad habit. When I copy code, I usually delete most of the comments from code where I understand what's going on. Otherwise I leave them.

I agree if I'm the only person using the code.
But whoever takes over my projects may not have as much VB experience as I have, still I may be over doing it.

**mendhak** · Mar 27th, 2002, 04:56 AM

Originally posted by GlenW

I agree if I'm the only person using the code.
But whoever takes over my projects may not have as much VB experience as I have, still I may be over doing it.

Yes, it would be easier if you had something like this

'now we're going to do this and this and this
related
lines
of
code

'next comment
more
lines
of
code

get my drift? of course your style would be for the beginners as you mentioned. You have to consider this: will the person who's coming next, be an expert or a novice? Act appropriately

**GlenW** · Mar 27th, 2002, 05:01 AM

Originally posted by mendhak

You have to consider this: will the person who's coming next, be an expert or a novice? Act appropriately

Exactly my problem I don't know, guess the best thing is to assume he's a novice and just annoy him if he isn't.

Any comments on the actual working of the Sub.

**cafeenman** · Mar 27th, 2002, 05:01 AM

When you have that many comments, you may also want to consider moving some more of them to the end of the code line so the code flow is a little smoother to read.

Anyway, it's not bad. Just not my preference. Like the man said, "Act accordingly."

**darre1** · Mar 27th, 2002, 05:03 AM

as said i think some of the more obvious lines don't need comments, but something i would add is at the start of the procedure add a few lines of comments explaining what each parameter in the procedure declaration does, and how it is used etc...

**GlenW** · Mar 27th, 2002, 05:05 AM

Keep them coming guys.
This is exactly what I need.

**wvisser** · Mar 27th, 2002, 05:10 AM

This is the first time that me being a novice in VB comes in handy; I'm the one you want judging your comments.

Yes, there are a lot of them and some trivial, even for me. But there's no harm in leaving them in. Allthough your example sub wasn't too hard to understand your comments helped me read through the code a lot faster.

I think that this commenting will get you there. But do keep in mind that if the next in line is a total newbie your comments may even have to clearer; as in the earlier posted

'now we're going to do this and this and this
related
lines
of
code

'next comment
more
lines
of
code

**MerrionComputin** · Mar 27th, 2002, 05:14 AM

A rule of thumb: The comments are sufficient if you can understand what a routine does and how when the code is removed.

VB Code:

'---------------------------------------------------------------------------------------
' Procedure      : FillFlexGrid
' DateTime       : 26/03/02 08:40
' Author         : Glen [email][email protected][/email]
' Purpose        : Fills MSFlexGrid with values in ADODB.Recordset
'                  If NewGrid is set to false inRes values are added
'                  to existing rows
'                  Else old rows are deleted
' Pre-Conditions : inGrid must have 1 or 0 FixedColumns
'                  inGrid must have 1 or 0 FixedRows
'----------------------------------------------------------------------------------    
    'If a new grid remove old rows
    'If NewGrid
        'If inGrid has a fixed row
            'Leave FixedRow
            'Clear all rows
        ' (inGrid.FixedRows = 1) Then
     ' (NewGrid)
    
    'Make inGrid columns = number of fields in inRes
    
    'To create row to add to grid
    'For loop count
    
    'If there are records
        'Go to the first one
        'While not at the last one
            'If inGrid has a fixed column
                'Make 1st value TAB
            ' (inGrid.FixedCols = 1) Then
            'While fields left
                'Add field value to thisRow & TAB to move to next Column
                'Next field
              ' For i = 0 To inRes.Fields.Count - 1
            'Add thisRow to inGrid
            'Reset
            'Reset
            'Next record
    ' (Not inRes.EOF)
 ' (Not (inRes.BOF And inRes.EOF)) Then
    
' FillFlexGrid

**GlenW** · Mar 27th, 2002, 05:14 AM

What about commenting Wend, Next and EndIf statements.
I do it all the time 'cos i think it can help if you have use deeply nested constructions.

This is really helping me.

**GlenW** · Mar 27th, 2002, 05:16 AM

Originally posted by MerrionComputin
[B]A rule of thumb: The comments are sufficient if you can understand what a routine does and how when the code is removed.

What a great idea!
Wish I'd thought of it.

**darre1** · Mar 27th, 2002, 05:31 AM

its always a good idea to comment your errorhandlers for errors that you have setup traps for too

**PilgrimPete** · Mar 27th, 2002, 05:43 AM

Good thread.
I'm an obsessive commenter, and agree with MerrionComputin - I sometimes comment before I start coding - helps me rationalise what I'm going to do, and (almost) makes up for the complete lack of design...

One thing that no-one has mentioned yet is Change History. Depending on your source code management system, it is sometimes useful to have a Change History section in your function header. Just lets you know why and when changes were made (and who made them!).

**GlenW** · Mar 27th, 2002, 05:46 AM

Originally posted by PilgrimPete
One thing that no-one has mentioned yet is Change History. Depending on your source code management system, it is sometimes useful to have a Change History section in your function header. Just lets you know why and when changes were made (and who made them!).

Good idea!

What format would you suggest?

**PilgrimPete** · Mar 27th, 2002, 05:52 AM

It's all down to taste really I guess, but something like this should do it...

VB Code:

'CHANGE HISTORY
'**********************************************************************************
'Date       | Changed By     | Bug ref       | Comments
'**********************************************************************************
'27/03/2002 | Pilgrim Pete   | 1234          | Added handler for RTE 7890

**darre1** · Mar 27th, 2002, 05:54 AM

oh i get yer. so when you make a change instead of deleting the line etc just comment it out and surround it in coments or seomthing, like this:

VB Code:

'ChangeDate: 27/Mar/2002 by Darrel Anthony
'Changed for this reason: dfhsdjkfhdsk
'*********************
'MsgBox "Original"
MsgBox "New Code"
'*********************

**darre1** · Mar 27th, 2002, 05:55 AM

ooh, pilgrim pete's is much better

**InvisibleDuncan** · Mar 27th, 2002, 05:56 AM

As a personal prefernece, I always use this for comments:

VB Code:

'# This is a comment

I find the # helps comments to stand out from lines of code that have been commented out...

**GlenW** · Mar 27th, 2002, 05:56 AM

Originally posted by darre1
oh i get yer. so when you make a change instead of deleting the line etc just comment it out and surround it in coments or seomthing, like this:

VB Code:

'ChangeDate: 27/Mar/2002 by Darrel Anthony
'Changed for this reason: dfhsdjkfhdsk
'*********************
'MsgBox "Original"
MsgBox "New Code"
'*********************

I think the idea is to list changes it in the header, so when someone can't get a function to work 'cos its been changed the explanation of the change is easy to understand.
Right?

**PilgrimPete** · Mar 27th, 2002, 05:58 AM

Darre1: not really what I meant, though it's useful if you have no config management tool, it soon gets really cluttered with old code (I've seen plenty of functions with more commented out code than active code

)
What I meant was to put it in the function header like this:

VB Code:

'---------------------------------------------------------------------------------------
' Procedure      : FillFlexGrid
' DateTime       : 26/03/02 08:40
' Author         : Glen [email][email protected][/email]
' Purpose        : Fills MSFlexGrid with values in ADODB.Recordset
'                  If NewGrid is set to false inRes values are added
'                  to existing rows
'                  Else old rows are deleted
' Pre-Conditions : inGrid must have 1 or 0 FixedColumns
'                  inGrid must have 1 or 0 FixedRows
'---------------------------------------------------------------------------------- 
'CHANGE HISTORY
'Date       | Changed By     | Bug ref       | Comments
''---------------------------------------------------------------------------------- 
'27/03/2002 | Pilgrim Pete   | 1234          | Added handler for RTE 7890
'----------------------------------------------------------------------------------

**mendhak** · Mar 27th, 2002, 06:04 AM

Here's a semi related question...

When's the best time to actually do the properly formatted commenting?

while working, or right towards the end, when you're cleaning up your code?

**MerrionComputin** · Mar 27th, 2002, 06:14 AM

When's the best time to actually do the properly formatted commenting?

Try writing the comments before you write the code...it works.
Like, suppose you want to want to set a new default printer by the name passed in....

VB Code:

Public Function SetDefaultPrinter(ByVal DeviceName As String) As Boolean
 
    '\\ Iterate through the installed printers
        '\\ If it is the desired printer
            '\\ set it to be the default printer
            '\\ indicate that the printer was found
            '\\ and stop searching
         '\\ Otherwise
     '\\ Next printer in list
          
 
End Function

See also Seven Secrets of Successful Programmers

**PilgrimPete** · Mar 27th, 2002, 06:14 AM

I recommend commenting as you go, because there's little chance you'll get round to, or be bothered to comment it when it's just about to go out the door...
Also if your memory is as rubbish as mine, you need aide memoires to remind you exactly why you did implement it that way...

Same problem occurs with documenting your design...

**cafeenman** · Mar 27th, 2002, 06:17 AM

We're supposed to document our design? Man, I can't even keep up with the help files, etc. My biggest app has almost 50 rtf files for the help project along with two user manuals, etc. I have to comment as I go along or I'm doomed. But forget about documenting the app. When I die, it dies with me.

**darre1** · Mar 27th, 2002, 06:24 AM

it's a well know fact that programmers hate documenting code anyway

Thread: Comments please

Thread Tools

Display

Comments please

semi...

Posting Permissions