General best practices: commenting code

[DaveC426913]

When you're commenting your code (and I don't care what language you're writing in), do you comment *before* the subprocedure or *within* the subprocedure? What is the best practice?

eg.

Comment before:

// loop through the following code
for i=1 to 10
---(some code)
---...
---// check truth of x
---if (x) then
------(some code)
---else
------(some code)
---end if
next

Comment within:

for i=1 to 10
---// looping through this code
---(some code)
---...
---if (x) then
------// x is true
------(some code)
---else
------// x is false
------(some code)
---end if
next

I can see advantages and disads of each.

I understand that the post obvious answer is "It doesn't matter, as long as it makes the code understandable." But I like consistency.

 

[faust9]

Both: The outer comment explains what the procedure does. The inner comments explain what each part of the procedure is for. If you clog the outer comment with too much info it makes quick reading of code difficult---when scanning code you should get enough info about code execution from the outer comments to know the framework of the program. The inner comments are used to explain the how's and why's of the functions/variables which isn't important when looking at the big picture.

 

[robphy]

One other variant of "inside" (if your language allows) is on the same line, e.g.
for i=1 to 10 // looping through this code

One advantage of this is that the code and comment are a little more tightly bound to each other... and show up together when grepped.

With more editors supporting "folding", I wonder how commenting styles may be influenced by this.

 

[mattmns]

I am new to programming. If I have a big related section then I will comment before on the entire thing. If something is small I put it on the same line, or right after.

Edit.. After looking at a recent program of mine I put some comments before and some after.

For example:

//start of something
{
something
}
//end of something

I guess whatever feels natural for me anyways.

 

[DrGreg]

As a general rule, I don't think it matters as long as it's clear, to whoever reads the code, where the comment belongs.

(Of course the specific examples of a comments given in post #1, e.g. "check truth of x" to explain "if (x)", would be pointless comments.)

However, if you are using some type of automated documentation system (such as Doxygen for the C++ language), you are forced to put certain types of comment before the thing they refer to.

 

[jim mcnamara]

FWIW - this ain't an "art form", folkks. There is a body of research on the subject - a fairly large body.

There are best practices for commenting. None of which has been encapsulated by the responses so far. Largely because it's not amenable to a one liner. For example, variable naming conventions are REALLY important to code commenting. Then there is the idea of self-doumenting code.

Large development houses require all programmers and analysts to have read
(for example):

McConnell, S., 'Code Complete', Microsoft Press 2004.

-- before they start work.

I wrote a small white paper on good coding practices once. I can post it here if you have the patience to read the durn thing.

 

[DaveC426913]

I wrote a small white paper on good coding practices once. I can post it here if you have the patience to read the durn thing.

That would be swell, yes.

 

[jim mcnamara]

This is a small white paper on code style and readability of code.
About 1/3 of it deals with comments.

All of it is aimed at C code, but it applies anywhere.

 

[nyhillp]

A clever non-programmer I am looking for feedback from actual programmers to see if my request specific to comments in code is reasonable. A generic question, my main concern is that of SQL Stored Procedures (SP).

Want current programming resource to include a brief English language comment toward the beginning of any new SP created that defines the purpose / function of the object.

Example: Truncates log files generated during the XYZ process, or Automates steps A, B and C to load batches into System X.

Is this reasonable? Notice most examples do not include the purpose of the object.

 

[CRGreathouse]

This is a small white paper on code style and readability of code.
About 1/3 of it deals with comments.

All of it is aimed at C code, but it applies anywhere.

Thanks for the paper, it looks great!

But wait, you think cyclomatic complexity is meaningful?

 

[stewartcs]

When you're commenting your code (and I don't care what language you're writing in), do you comment *before* the subprocedure or *within* the subprocedure? What is the best practice?

...

I can see advantages and disads of each.

I understand that the post obvious answer is "It doesn't matter, as long as it makes the code understandable." But I like consistency.

I was taught that you comment at the beginning to define the inputs, outputs, side-effect, etc. But also anywhere else that needed clarification (i.e. where the code wasn't "obvious").

CS

 

[CRGreathouse]

I was taught that you comment at the beginning to define the inputs, outputs, side-effect, etc. But also anywhere else that needed clarification (i.e. where the code wasn't "obvious").

That's how I do it.

 

[chroot]

I use two styles of comments. I put large comments, almost prose-like, above each major block of code. I set these apart from the code with blank lines and perhaps rows of slashes or other devices. These block comments explain in plain english what the following block is going to accomplish and how it works.

Then, I put individual line comments above any tricky or especially important lines within the block.

- Warren

 

[kenewbie]

In my not so humble opinion:

If the purpose of a function or method is known, and you cannot follow the code, at least one of these are true:

- You do not understand the concepts used (ie, you cannot follow the math)
- The code is too complex and should be subdivided into more functions or methods
- The code is badly written (ie using non descriptive names for variables)

Thus, comments are only needed to explain the input/output of a function or a method.

k

 

[Eus]

This is a small white paper on code style and readability of code.
About 1/3 of it deals with comments.

All of it is aimed at C code, but it applies anywhere.

I have read that thoroughly and indeed it is a good white paper.

Ah, I have spotted some typos also and here I give you the revised version.


Eus

 

[-Job-]

In C# i often comment using regions or not at all and let descriptive class, function and variable names do the talking. Lots of comments can get in the way of reading the code (in my opinion). When looking through someone's code my first step is usually to quickly glance at the comments and then remove all of them. I dislike line-by-line comments (they tend to get unnecessarily lengthy and specific), i prefer a few lines at the top of a function or class that describe the general implementation approach plus any remarks on less intuitive parts of the code.

 

[jim mcnamara]

When I ran a develpment shop we had comment standards for C, BASIC and FORTRAN plus some other languages you've never heard of.

And job is right: excessive comments get in the way of reading the code.

Without getting into Halstead code metrics, readability of code translates in a big way to vocabulary. An analogy is English class. If you examine Shakespeare's 'Romeo and Juliet' and then look at the King James version of the Bible (both written within a few years of each other) you will find that Shakespeare ransacked the English lexicon, while the writers of the King James version used less than about 6000 English words.

Reading Shakepeare can be an exercise in using the dictionary - all the extraneous effort going into simple comprehension of the text gets in the way of the story. Excessive comments in code do the same thing - they get in the way of the story. Using descriptive consistent variable naming makes it easy to comprehend logic. It keeps the vocabulary count down. Keeping variable scope limited -- ditto.

 

[zyh]

This is a small white paper on code style and readability of code.
About 1/3 of it deals with comments.

All of it is aimed at C code, but it applies anywhere.

I have read that thoroughly and indeed it is a good white paper.

Ah, I have spotted some typos also and here I give you the revised version.


Eus

Thanks, it's great. I use both of commenting types before and after (I'm using c/c++), and the doxygen could recognize them by “//!” (before) and “///<” (after) styles.

But, in my opinion, using comment is not enough, sometimes; I think it's hard to draw a flowchart in cpp files.even; I'd like to add some picture describing more complicated structures. By the way, does someone heard that a code editor support embedded images?

Thanks.