Comment on Comments.(Request for Discussion)

[patrician]

Hello All

In a thread a week or so ago, someone suggested that they were going to start a thread about the use of comments. As no one has so far taken this task in hand here are a few things to discuss.

Are comments a good thing or a bad thing, in that they become an excuse for not writing proper support documentation?

Does code written with clearly named variables(ie self describing code) need comments?

Is overcommented code as bad as poorly commented code?

At what size would a sub/function not need comments?

There are loads more things to be said about comments but hopefully these will start the ball rolling.

This has become a subject dear to my heart in the last few weeks. I have taken over a number of sizable VB projects which came with no commented code and minimal, if any, docs.
Some parts of the code have obviously been taken from the internet and MSDN and the only changes made to the code has been the removal of comment, go figure.

Personnally, I have always used comments at the start of a sub/function to describe it as well as the parameters used, but not had a comment as every second line of code, also I would comment any particularly tricky pieces of code. For a while on smaller projects I would also include a module called readme which would be filled with comments about program structure and flow, the things that might be system docs but then again who can ever find system docs for programs written years ago.

Anyway, hopefully this has given you something to think about over the weekend ;-)

 

[danceman]

comments I beleive are a good thing. like you I have had to maintain old code to find no documentation or comments. I like to comment on calling subs and in the sub what are the parematers passed and what is the outcome. I also lie to add comments showing code that reflects a change

' rev 3.0.02
bla,,,bla...
more code

' end of rev 3.0.02 Attitude is Everything

 

[Foada]

Can o' worms? I do not think we will see too many people disagree with the comments are a good thing argument. What I think will become more of the point of the discussion will be what to comment. For example:

Private Sub cmdArray_Click(Index As Integer)
Dim cmd As CommandButton

For Each cmd In cmdArray
cmd.Caption = cmd.Index
Next

End Sub

Is pretty straight forward and the names of the objects explain the procedure, therefore it is my opinion that something simple like this only becomes cluttered with comments. Some things that I believe should always be included in every file is a header. Something like this

' File:
' Header.Cls
' Author:
' Sam I Am
' Description:
' This is An Empty Class Header File
'-----------------------------------------------------------------------------------------------------------------------
' Revisions:
' Original 7/31/2002
'-----------------------------------------------------------------------------------------------------------------------
' Functions And Subroutines:
'-----------------------------------------------------------------------------------------------------------------------
' Properties:
'-----------------------------------------------------------------------------------------------------------------------
' Required Functions,Subroutines,Properties,Variables,Etc.:
'-----------------------------------------------------------------------------------------------------------------------
' Variables:
' Public:
'-----------------------------------------------------------------------------------------------------------------------
' Private:
'-----------------------------------------------------------------------------------------------------------------------
' Constants:
' Public:
'-----------------------------------------------------------------------------------------------------------------------
' Private:
'-----------------------------------------------------------------------------------------------------------------------
' Enumeration:
'-----------------------------------------------------------------------------------------------------------------------
' Special Notes:
' Printing Line Length is 120 Characters
'-----------------------------------------------------------------------------------------------------------------------
' Naming Conventions:
'-----------------------------------------------------------------------------------------------------------------------

I place this in every piece of code I write for a couple of reasons. First if it is there other people who edit the code will be more likely to use it, especially when it comes to revision, and secondly it allows any one who opens the file a chance to see what you were thinking when you wrote it. Maybe the most important reason being when you go back to the code after a year and add the module to another project you can get a feel for what you need to do to use the code. Just a few thoughts.



If you choose to battle wits with the witless be prepared to lose.

 

[strongm]

Consider the following progression:

a = b * c

a = b * HourlyRate

a = NumberOfHoursWorked * HourlyRate

TodaysPay = NumberOfHoursWorked * HourlyRate

currTodaysPay = dblNumberOfHoursWorked * currHourlyRate

At which point would does the code become sufficiently self-documenting to not require comments?

 

[Foada]

Then there is this

a^2 = b^2 + c^2

0r

linSide(1).X1 - linSide(1).X2 ..........

You know what I am getting at.

In this case less name and no comment or brief comment is a much clearer code. If you choose to battle wits with the witless be prepared to lose.

 

[CCLINT]

My thoughts as well StrongM.
As I write lines of code, when it is basically, as you say, "self-documenting", I think: "If someone has a problem with this maybe they shouldn't be reading my code"

I have made the mistake in not describing a proceedure correctly, thinking: "I'll never forget this one", and came back to it 3 months later and said: "huh?". It would take a while to start the thought pattern that was used here again and figure out what the heck I intended and how it tided in with the caller or whatever. After I got going again it would be no problem - the only problem is lost time....and money.

 

[CajunCenturion]

I can jump on this bandwagon - Comments are a good thing. That's the easy part. The meat is how much do you need? strongm's progression provides an interesting stepladder. As you progress down the list, less and less commenting is required, with only the last two lines IMHO being candidates for no comments required. The only thing that I don't know are the type and/or scope of the variables in question (I know - different thread). But the choice of variable naming standards - and thus the amount of information conveyed by the name, is a parameter to the "how much commenting do we need" function.

I am a fan of modularity (some have said to the extreme), in that subs and functions are fairly atomic in nature - that being they do one thing, and let's hope they do it well. In that case, one or two sentences should be sufficient to explain the purpose of that routine. The more complex the algorithm, the more detailled the explanation needs to be.

The thing that drives me crazy, when a programmer has chosen to "trick" the program to do something that is not intuitively obvious. Perhaps a weak example could come from a post I made in a previous thread where I am setting the RowHeight of certain rows in a grid to hide that data which did not meet certain search criteria. The fact the grid actually contains all the data, and not the true results of the search is something that should be pointed out clearly in comments. Good Luck
--------------
As a circle of light increases so does the circumference of darkness around it. - Albert Einstein

 

[CasperTFG]

I don't think we should be affraid to comment a lot of the code anyway.

When compiled the comments are dropped so there is really no excuse not to comment.

I realy only comment Global variables, or things that I know would be hard to understand. Things like

curTotalCharge = curRate * intHours

Would be self explanitory. But if I were to do something like:

curTotalCharge = ((curRate * intHours) + ((curRate * intHours) * .15)) * intExchange.

I would probably commant that. By the time I look back to figure what each variable means a simple comment such as

'Get total charge including taxes in Canadian Currency

would ahve helped me figure out what the heck i was trying to do.

All in all I would say if it is obvious to you waht the code does i.e. you didn't have to look up syntax or figure out which variables to use, it is probably ok to leave it as is. But if it took you more than 3 minutes to write the line you better comment it.

Craig, mailto:sander@cogeco.ca

Remember not to name the Lambs...
It only makes the chops harder to swallow

 

[MichaelRed]

Just to be the contrarian, comments are (at least CAN BE) a BAAAAAAAAAAAAAAAAD thing.

Some will over comment the obvious which just clutters the mind. e.g.

[tab]Dim MyPay as Currency 'Force calc to use currency type


Some will comment with mis-leading (e.g. WRONG) info. e.g.

[tab]MyPay = basCalPay(Hrs, Rate)[tab][tab]'Return Net Pay (w/ tax and SS taken out)

[tab]NetPay basDoTax(MyPAy, TaxRate)

[tab][tab]'
[tab][tab]'
[tab][tab]'
[tab][tab]'

Public Function basCalcPay(Time as Single, PayRate as Currency) as Currency

[tab][tab]basCalcPay = Time * PatRate

End Function

I can recall WAY to many of these - going back as far as assembler programming. After a (short) perusal of a prog / function many will exhibit some form of misleading commentary. Shortly thereafter, the prudent programer will erase all commentary and proceede to re-doeument the procedure(s). Using hte "self-documenting' approach of using 'descriptive variable names' can just as easily fall into the same erronous problems. Many of the 'bad comment' errors dpring from revising a procedure but failing to review the procedure AND it's calling procedures to assure complliance with the adopted conventions (both naming and comment requirements).

I am NOT aginst adopting either naming conventions OR comment requirements, just pointing out the endless potential for deception. I believe ONE of the better approaches is the "atomic procedure", where NO procedure is so complicated that it should have more than a few lines in the header to describe it's purpose. Of course, that leads to jumbles lines of code as (to borrow from the earlier pseudo code)


[tab]NetPay basDoTax(basCalPay(Hrs, Rate), TaxRate)


MichaelRed
m.red@att.net

There is never time to do it right but there is always time to do it over

 

[strongm]

I have to admit that it's been a long time since I've been part of a development team, and for many years the code I've written has been for myself or as tools to assist in the management of corporate IT infrastructure. As a result I'm probably lazier than many in this forum when it comes to commenting (particularly since I don't necessarily have to follow any imposed standards). Bearing that in mind, here's my general approach.

I always provide a header comment for each and every function, method, property and sub. I don't quite include as much info as foada, but along the same lines. I even wrote myself a little IDE add-in to insert a partially filled-in template at the click of a button, so as to eliminate some of the tedium (and I suspect most people find commenting a tedious procedure, albeit necessary, so anything that makes it easier has got to be a bonus). Then, within the functions, methods, etc. I try to make the code as self-documenting a possible (i.e around about step 5 on the progression I gave earlier). Where the code may be a little obtuse in what it is trying to achieve (or in my parlance "a neat trick&quot I will generally provide some explanatory text.

What I don't do, and don't feel I need to do in my position, is document every line of code; MichaelRed's observation about over-commenting is, IMO, quite valid.

 

[CajunCenturion]

A related documentation comment. In another thread the following statement was presented -

If (main.Left - speed <= other.Left + other.Width) And (main.Left - speed >= other.Left) And (main.Top <= other.Top + other.Height) And (main.Top >= other.Top) Or (main.Left - speed <= other.Left + other.Width) And (main.Left - speed >= other.Left) And (other.Top <= main.Top + main.Height) And (other.Top >= main.Top) Then

We're focusing stricly on documentation here folks

This is a complex boolean expression in which only the elementary expressions are contained within parenthesis. Parenthese are NOT used to explain how the individual expressions are to be combined. It is my opinion that NOT fully parenthesizing such expressions is a bad practice on two fronts - relying on compiler defaults, and a failure to properly document the code. Fully parenthesizing expressions - removing all ambibuity with respect to the order of equal level operators - is just as important in explaining the meaning and purpose of the code, as is using meaningful variable names, and inclusion of other pertinent comments within the code. Good Luck
--------------
As a circle of light increases so does the circumference of darkness around it. - Albert Einstein

 

[DarenNM]

Like many things, if used properly they (comments) are good. If misused, they can be confusing.

Things like

 iResult := 6; {Set iResult to 6 }

aren't very helpful either. We can see that iResult is being set to 6.

I often use comments to show why a piece of code has changed and who within the organisation requested it so that when I come back to it a third time I don't wonder why I changed it (so I don't change it back!).

There is a good discussion on the use of comments at

http://mindprod.com/unmain.html

Well worth a look

Daren