SourceForge has been redesigned. Learn more.
Close

#180 Forbid endline comments

release_3.4
closed
Check (274)
5
2012-10-10
2003-05-28
Dale King
No

Steve McConnel in "Code Complete" suggests that endline
comments are a bad practice. An end line comment would
be one that is on the same line as actual code. For example:

a = b + c; // Some insightful comment
d = e / f; // Another comment for this line

Quoting "Code Complete" for the justfication:

"The comments have to be aligned so that they do not
interfere with the visual structure of the code. If you don't
align them neatly, they'll make your listing look like it's been
through a washing machine.

"Endline comments tend to be hard to format...It takes time
to align them. Such time is not spent learning more about
the code; it's dedicated solely to the tedious task of
pressing the spacebar or tab key.

"Endline comments are also hard to maintain. If the code on
any line containing an endline comment grows, it bumps the
comment farther out, and all the other endline comments will
have to bumped out to match. Styles that are hard to
maintain aren't maintained....

"Endline comments also tend to be cryptic. The right side of
the line doesn't offer much room and the desire to keep the
comment on one line means the comment must be short.
Work then goes into making the line as short as possible
instead of as clear as possible. The comment usually ends
up as cryptic as possible...."

"A systemic problem with endline comments is that it's hard
to write a meaningful comment for one line of code. Most
endline comments just repeat the line of code, which hurts
more than it helps."

His comments on being hard to maintain when the size of
the line changes are even more important in the age of
automated refactorings.

So I propose a check that requires that comments be the
only thing on a line. For the case of // comments that
means that the only thing that should precede it is
whitespace.

It might be desirable to have an exclusion for /**/ comments
within a statement. For instance, I will sometimes do things
like:

Thread.sleep( 10 /* milliseconds */ );

Another exclusion (which should be user selectable) is for
an endline comment on a line ending with a }. Many people
like to do things like the following:

while( condition )
{
    statements;
} // while

Although I personally disagree with this practice an
exception should probably be made for those that practice it
as long as it is user selectable.

It may be possible to do all this with a special case of
GenericIllegalRegexp check, although it would probably be
a comlex regexp. If so then we might want this as an
example there.

Discussion

  • Tim Tyler

    Tim Tyler - 2003-06-13

    Logged In: YES
    user_id=796025

    I've written a check that does this:

    ``Checks for lines with trailing comments

    This check reports lines with trailing comments - where the
    rest of the line matches a given regular expression...''

    <module name="TrailingComment">
    <property name="checkCStyle" value="true"/>
    <property name="checkCPPStyle" value="true"/>
    <property name="matchForBlankLines" value="^
    [\s});]*$"/>
    </module>

    Notes:

    The comment /must/ end the line - i.e.:

    The check ignores "Thread.sleep( 10 / milliseconds / );"
    - on the grounds that that's not a trailing comment.

    The regular expression is intended to deal with the
    "} // while" example.

    I'm not sure whether distinguishing C/C++ comments
    is useful or pointless - but currently it's in.

     
  • Oleg Sukhodolsky

    Logged In: YES
    user_id=746148

    module TrailingComment. Committed to CVS for 3.4

     

Log in to post a comment.