5

I am asking this because I have seen places where, whoever coded initially had provided proper comments, but later on modifications were made to the code but the comments were left untouched. I remember reading somewhere " Don't get suckered in by the comments, debug only code".

So is it a good/ relevant/ practical idea that tells the scope of the comments so as to prompt the developer for editing the comment.

Your thoughts.

migrated from stackoverflow.com Nov 24 '11 at 15:39

This question came from our site for professional and enthusiast programmers.

  • I don't know what you mean by "tells the scope" -- but that's wise advice you received in the past. (Someone here once apologized for all their comments being in Russian -- but it was wonderful -- because I couldn't read them, they couldn't lead me astray. When debugging, definitely ignore the comments.) – sarnold Nov 23 '11 at 10:00
  • by scope i mean that the comments come with their own scope. That they are applicable only to the portion in the code. Having that would tell a developer that if any logic has changed in the sub routine then comments need to be adjusted too. – Rig Veda Nov 23 '11 at 10:04
  • 1
    Developers should revise comments whenever they change code. It should be innate behaviour. – Lloyd Powell Nov 23 '11 at 10:05
  • If the code and the comments disagree, then probably both are wrong. – Kaz Dragon Nov 23 '11 at 10:25
  • fyi, that quote is Dave Storer if I recall correctly – CaffGeek Nov 24 '11 at 16:20
3

Definitely. All comments have scope, whether implicit or explicit. As a general rule, it's helpful to your successors to be reasonably explicit about scope.

Vertical space is an inexpensive way to delineate scope.

I often try to convey scope when writing comments by either:

  1. inserting a linebreak or two before the comment, to keep it visually grouped with the block of code whose behavior it's intended to document
  2. or defining a logical block of code, and adding the comment at the top of that block.

In C, #1 would look like:

doStuff();
doOtherStuff();

// comment explaining the intent of the following three lines
int i;
for(i=0;i<10;++i)
    doMoreStuff(i);

doOtherStuff();

In C, #2 would look like:

doStuff();
doOtherStuff();

{
    // comment explaining the intent of the following three lines
    int i;
    for(i=0;i<10;++i)
        doMoreStuff(i);
}

doOtherStuff();

In this second example, the extra curly brackets also help by minimizing the scope of variable i.

  • 1
    Basically yes, but defining a new function with proper name is often better option: function then becomes THE comment and is checked by compiler (doesn't rot so quickly). – MaR Nov 24 '11 at 15:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy