Comments

Muhammad Uzair
What are Comments?
A comment is a text note added to source code to
provide explanatory information, usually about
the function of the code.
To Comment or Not to Comment

 We’ll encourage commenting, but we won’t be

naive about it. We’ll have code reviews so that
everyone will get a good sense of the kind of
comments that actually help. If you have trouble
understanding someone else’s code, let them
know how they can improve it.”
Kinds of Comments

 Comments can be classified into five categories:

 Repeat of the Code
 Explanation of the Code
 Marker in the Code
 Summary of the Code
 Description of the Code’s Intent
Repeat of the Code

 A repetitious comment restates what the code does in

different words. It merely gives the reader of the code
more to read without providing additional information.
 Example:
 i=i+1 //Add one to i
Explanation of the Code

 Explanatory comments are typically used to explain

complicated, tricky, or sensitive pieces of code. In such
situations they are useful, but usually that’s only because
the code is confusing.
Marker in the Code

 A marker comment is one that isn’t intended to be left in

the code. It’s a note to the developer that the work isn’t
done yet. Some developers type in a marker that’s
syntactically incorrect (******, for example) so that the
compiler flags it and reminds them that they have more
work to do.
 Example:
 // ****** NOT DONE! FIX BEFORE RELEASE!!!
Summary of the Code

A comment that summarizes code does just that It

distills a few lines of code into one or two
sentences. Such comments are more valuable
than comments that merely repeat the code
because a reader can scan them more quickly
than the code.
Description of Code’s intent

A comment at the level of intent explains the

purpose of a section of code. Intent comments
operate more at the level of the problem than at
the level of the solution.
 Example:
 // get current employee information
Effective Commenting
 There are Some Rules for Effective Commenting:
 Rule 1: Comments should not duplicate the code.
 Rule 2: Good comments do not excuse unclear code.
 Rule 3: If you can’t write a clear comment, there may be
a problem with the code.
 Rule 4: Avoid personal notes, remarks, jokes, etc.
 Rule 5: Provide links to the original source of copied code.
 Rule 6: Add comments when fixing bugs.
 Rule 7: Avoid endline comments for multiple lines of code.
Rule 1: Comments should not duplicate the code
Rule 2: Good comments do not excuse
unclear code

 Another misuse of comments is to provide information

that should have been in the code. A simple example is
when someone names a variable with a single letter and
then adds a comment describing its purpose
Node n; // best child node candidate
 The need for comments could be eliminated with better
variable naming
Node bestNode;
Rule 3: If you can’t write a clear comment, there
may be a problem with the code

 Ifyou write lengthy comments, stop and review

your code. More often than not, it means that
your code can be simplified and improved.
Rewrite the code to something you understand
well enough to explain.
 Unix Source Code “You are not expected to
understand this,”
Rule 4: Avoid personal notes, remarks, jokes, etc.

 //RIPJSB 1750
 If your comment causes confusion instead
of dispelling it, remove it.
Rule 5: Provide links to the original source of
copied code
Rule 6: Add comments when fixing bugs
 Comments should be added not just when initially
writing code but also when modifying it,
especially fixing bugs.
 It not only help the reader but also help the
testers that how to test the code if a specific bug
is found.
 Example: // Use the name as the title if the
properties did not include one (issue #1425)
Rule 7: Avoid endline comments for
multiple lines of code

 Ifan endline comment is intended to apply to

more than one line of code, the formatting
doesn’t show which lines the comment applies to.
Optimum Number of Comments

 Studiesat IBM found that a commenting density of

one comment roughly every ten statements was
the density at which clarity seemed to peak.
Fewer comments made the code hard to
understand. More comments also reduced code
understandability.