Fog Creek Software
Discussion Board

Comments in code

I have beening reading CODE COMPLETE and it is very helpful.  The more I read it,  the more I disgust myself for no writing proper code (mainly because the firm I work for doesn't really care how ugly or buggy, as long as it works for now. fix the bug later).

Maybe I am not alone.  So I ask you all.

Do a lot of people write comments in their code?
ie 1. Description of Routine.
    2. Parameters descriptions
    3. Error Conditions
    4. Algorithim used & why it is used
    5. Example Input, Output
    6. PDL (Program Design Language from CODE COMPLETE)
    7. History

When is it considered overkilled ?


Friday, April 5, 2002

nPage, you bet I comment. In fact, for non- trivial functions, I solve my problems in comments before writing a line of code, such that the code is just the implementation of the English comments.

I have found that I cannot maintain my own code even two weeks later if I have not done this. I have learned from experience that if I haven't commented it, I won't understand it quickly later, so I can't expect others to, either. This includes documenting each parameter along with expected values, etc. When I have completed a given routine, I patch the comments to match; this usually takes only a minute or two. Forparticularly important routines, I add calls/call-by/read/modify liststo the function header. Depending on the language, this may be automatedwith scripts or utilites (like C-DOC).

Any changes made to the code later get an explanation of why the change, with the old code commented out rather than deleted. That has saved me more than once when a change didn't go as smoothly as hoped.Also, my "why we don't do it like this anymore" comments have savedme on much-later maintenance.

I have a three-pass habit when writing a routine, and while it may seem to take longer than the standard one-pass, I find I spend less overall time on any given code doing it this way, because I solvemy problems before adding the complication of code:

1. Write the comments with what I plan to do, and how I plan to do it in a step-by-step manner (usually numbered steps). Problem-solving happens here rather than while writing the code since the comment language (English) is easier to modify.

2. Write the code implementation of the comments. Clean up comments to match the code.

3. Possibly re-write the code specifically to make it as easy to follow as possible, with an eye on reducing memory usage and cpu usage. Sometimes after coding, I find that some variables can be eliminated, some branches can be rewritten more intelligently, etc. If this is the case, I rewrite the routine from scratch. (It's not a rewrite since it hasn't been in production yet). Routines usually get 10% - 50% smaller when I do this, and thus easier to maintain.

Troy King
Friday, April 5, 2002

That depends highly on who you ask. I like adding a one-liner comment for each public method that clarifies what it does. Apart from that, I spend a lot of time thinking about appropriate names for my methods and variable names, which eliminates the need for many comments. When I do comment inline, it's usually to explain WHY I did something, and not what is going on.

In perspective, when the code is as self-describing as it can get, and it still isn't obvious what is happening, a comment is helpful.

The problem with over-commenting is that you must be careful to maintain them along with the code, and you don't get compiler or run-time errors when there are bugs in the comments.

Friday, April 5, 2002

> Do a lot of people write comments in their code?

It varies, by person, by project, and over time.

> 1. Description of Routine.

A good thing, if you're gong to comment anything at all (beyond simply choosing a good name). An even more helpful thing to comment IMO is global variables, and/or the member data variables of a class.

> 2. Parameters descriptions

Useful if anyone else is going to call this routine: your carefully-chosen name might not be as self-descriptive as you hope.

> 3. Error Conditions

If not, at least specify error handling: an exception or a return code, and who (caller or callee) should emit any error message.

> 4. Algorithim used & why it is used

I generally don't; in most routines the algorithm is simple (a for loop, an if-then-else). If it's a complicated algorithm (e.g. an image compression/decompression, or a communications protocol), then a reference to the book which defines the algorithm being implemented.

> 5. Example Input, Output

Don't write a routine unless it's used in real life: because it cannot be tested! So if it's for in-house use, there will already be a real-life example of its being used, and so no need to write an extra "example". On the other hand if you're giving a library to outside developers, a sample application is desperately useful.

6. PDL (Program Design Language from CODE COMPLETE)

Might as well, if you think that way.

7. History

I don't. I have a version-control software database for in-house use, and release notes for external use.

Christopher Wells
Friday, April 5, 2002

Absolutely, yes. I agree with everything Troy wrote, ecept that we have a good version control system so we don't write history comments. Even then I write 'why we don't do it this way' comments.

Adding comments takes a trivial amount of time if you do them afterwards, and if you  write them before they will probably save you time. Even if nobody else in your company writes comments, start doing it now. You will probably find that everyone else thinks its a good idea, they just don't get around to it.

David Clayworth
Friday, April 5, 2002

David is correct about "why we don't do it this way" comments. They save lots of money and confusion down the road. They do not become out-of-date as quickly as "why we *did* it" comments, so they have more staying power.

Rejecting alternate methods is time-consuming enough without the process being repeated every time the code is maintained. Go for the comments that are money-makers.

Friday, April 5, 2002

Many languages have a documentation genration tool associated with them.  In java it is Javadoc.  When I did C++ Code, I used Doc++, which I think has been superceded.  Perl Has PERLDOC.  If you are going to take the time to write a comment, it almost certainly should be compliant with one of these tools.  Even if You don't write the comments, it is handy to generate the documentation in a bare bones form to use as a road map.  The cool thing is that you can add in the other things you have (like UML diagrams) as part of the package level documentation, so you can keep the docs alive as part of the coding proces.

Anyone else notice that  coding and docing use the same letters?  Pup backwards is still pup, but Dog backwards...

Friday, April 5, 2002

The flip side of this, of course, is when reverse-engineering code (as opposed to maintaining it), ignore the comments, and pay attention to the code.  I can't even begin to count the number of times I've come across verbose comments that incorrectly described the code they were attached to.  Either the code changed and the comment didn't, or the person writing the comment didn't really understand what they were commenting on.

James Montebello
Friday, April 5, 2002

Comments are good, but the main contribution I found code complete making to my code was in making it less complex.  I used to take pleasure in creating C programs with truly tight formatting, function calls in if statements etc.  By rolling all of this stuff out I have firstly made the code more readable.  Secondly it actually made me see the other possibilities and generally optimise the code better.  I find it's real difficult to spot how to make some code better when it's all embedded in a single statement, but a lot easier when you have all the statements rolled out in a line.  You can spot how it works a lot better, and feel free to move the code as needed.  Comments are useful, but the code shouldn't be so complex as to need to many to explain the actual working of the code, just it's purpose.  And perhaps those funnies that creep in out of necessity.

Colin Newell
Saturday, April 6, 2002

I don't think that comments are good. More like a necessary evil. I reckon that most of the time it really *is* possible to produce self-documenting code. I do occasionally use comments, but this usually leaves me with a feeling that I somehow failed to clarify the design sufficiently. 

There are two kinds of situation where I find comments to be useful.

First, where there is an apparently obvious way of doing something which for some reason is not appropriate (David's "why we don't do it this way" comments). I'll make a note of why I didn't do the obvious so that I don't retrace my steps when refactoring.

Second, where there is some performance reason for organising the code in such a way that it becomes complicated or difficult to read. In other words, where self-documenting code would run too slowly.

I'm a big fan of very descriptive method names and very descriptive variable/argument names. I also like breaking out separate operations into separate methods as far as reasonably possible. That helps in making code self-describing too. I hope that my actual source code is as readable as comments, for example...

If Not MyWindow.IsWideEnoughToDisplay(PictureToDisplay) Then

I work mostly in VB, and I think that this influences my views. For example, one rarely needs to type out the full name of anything, so for one's typing workload, it's irrelevant how long the names are. Also, you can easily do project-wide search and replace if you decide to change the name of something. Both influences make me more inclined to think hard about explicit naming and less about avoiding keystrokes.

I collaborate with C++ programmers. In my experience they favour conciseness over disambiguity (even in conversation). They laugh out loud sometimes at the length of the class and method names I use (even the VB compiler sometimes complains at me).  I remain unrepentant. Here's an example of a method declaration from the project I have open right now:

Friend Function GetAntiClockwiseAngleDifferenceDegrees(ByVal OtherAngleDegrees As Single) As Single

(The project uses radians in some places.) I guess I could have saved some typing, and written it like this:

Friend Function AngDiff(Byval Ang As Single) As Single

More concise? Yes. More ambiguous? Surely. It's going to take some commenting to make it reliably useful.  I reckon that by the time the sofware ships, the initial urge to be concise would have meant that I ended up making more keystrokes, not to mention making more mistakes when I didn't want to interrupt my flow to check exactly how the function works.

Charles Monk
Sunday, April 7, 2002

I generally agree with the "use long, descriptive names" school of programming, but if all your functions and variables are 25 letters long, it gets hard to read from sheer verbosity.

I think the ideal is to apply huffman coding to how you name  them - the less used and obscure they are, the longer and more descriptive the name - and vice versa.

NumberOfStudentsInClass is better than StuCnt

abs is better than AbsoluteValue

Sunday, April 7, 2002

I agree: make member names long only in order to make them more descriptive, not for the sake of making them long. If every member name was 25 characters, then it would be hard to read.

The idea is to make names longer only in so far as it improves comprehensibility, and how things are comprehended of course depends on context. Often the context can unambiguously clarify the meaning and role of a member name.

Charles Monk
Sunday, April 7, 2002

*  Recent Topics

*  Fog Creek Home