Scribd
Upload
14 views

Clean code comments

Uploaded by

alashkar.ayman95
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
14 views

Clean code comments

Uploaded by

alashkar.ayman95
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 43

Comments

Comments don't Make Up for


Bad Code.
It should be a prerogative of a developer to write
code that expresses itself. In this light, comments
can be seen as failures.
Document “Why”
This is the information you can include in the comments:
• WHY the code does what it does. Why the code is
written.
• WHAT it does, but this only if it is really necessary.
• HOW it does is the last thing, as priority, you should document.

How should be pretty straightforward from the code. If not, the code
needs to be refactored.
Of course, there are exceptions. If the code uses an algorithm that is not
common knowledge (for example calculating a pair of public - private
keys), then it might be useful to document how the code is achieving the
result.
Comments Do Not Make Up for Bad
Code
Comments in the code should be used only when naming
fails to explain thoroughly the code.
If a comment is needed, the first option should be to try to
improve the code so it does not need an explanation.

Comments are not code


If the code is not clear, do not comment to improve it. Fix the
code as much as possible. Do not use comments to improve
bad code. The comments should be replaced by
code as much as possible.
Comments Do Not Make Up for Bad
Code
A comment like:
//draw a circle at screenCenterPoint with radius 10

Is not needed when the call code is :


drawACircleAtPoint(screenCenterPoint, radius:10)

Explain Yourself in Code

vs
“Don’t comment bad code—rewrite it.”
Good Comments
Some comments are necessary or
beneficial. However the only truly good
comment is the comment you found a
way not to write.
Legal Comment
Sometimes our corporate coding standards force us to write certain
comments for legal reasons.
For example, copyright and authorship statements are necessary and
reasonable things to put into a comment at the start of each source file
Informative Comments
It is sometimes useful to provide basic information with a
comment.
Explanation of Intent Comments
Sometimes a comment goes beyond just useful information
about the implementation and provides the intent behind a
decision.
Clarification
Sometimes it is just helpful to translate the meaning of some
obscure argument or return value into something that's
readable.

In general it is better to
find a way to make that
argument or return value
clear in its own right; but
when its part of the
standard library, or in
code that you cannot
alter, then a helpful
clarifying comment can be
useful.
Warning of consequences
Sometimes it is useful to warn other programmers about
certain consequences.
TODO / FIXME Comment
It is sometimes reasonable to leave “To do” notes in the form
of //TODO comments.
In the following case, the TODO comment explains why the
function has a degenerate implementation and what that
function's future should be.
TODO / FIXME Comment
TODOs are jobs that the programmer thinks should be done.

• A Reminder to delete a deprecated feature


• A plea for someone else to look at a problem.
• A Request for someone else to think of a better name
• A Reminder to make a change that is dependent on a
planned event.

Whatever else a TODO might be, It is not an excuse to leave


bad code in the system.
TODO / FIXME Comment
Of course, in a perfect world the developer should refactor
the code on the spot. But, sometimes there are reasons you
cannot do it:

• The issue you are working on is not related to the bad


piece of code
• You do not have the knowledge to fix it
• It will take a long time to fix it
• There is a big risk in doing it
• The current task is urgent, for example a critical
production issue, and business reasons are stronger than
refactoring and code beauty
Amplification
A comment may be used to amplify the importance of
something that may otherwise seem inconsequential.
Bad Comments
Usually they are excuses for poor code or
justifications for insufficient decisions,
amounting to little more than the
programmer talking to himself.
Mumbling
Plopping in a comment just because you feel you should or because the
process requires it, is a hack. If you decide to write a comment, then
spend the time necessary to make sure it is the best comment you can
write.
What does that comment
in the catch block mean?
Clearly meant something
to the author, but the
meaning not come
though all that well.
Apparently, if we get
an IOException, it means
that there was no
properties file; and in
that case all the defaults
are loaded.
But who loads all the
defaults?
Redundant Comments
What purpose does this comment serve? It’s certainly not more
informative than the code. It does not justify the code, or provide
intent or rationale.
It is not easier to read than the code. Indeed, it is less precise than
the code and entices the reader to accept that lack of precision in
lieu of true understanding.
Misleading comments / Lying
Comments
Sometimes, with all the best intentions, a programmer makes a
statement in his comments that isn't precise enough to be accurate.

Example: The method does not return when this.closed becomes true. It
returns if this.closed is true; otherwise, it waits for a blind time-out and
then throws an exception if this.closed is still not true.
Mandated Comments
It is just plain silly to have a rule that says that every function must
have a javadoc, or every variable must have a comment.
Comments like this just clutter up the code, propagate lies, and
lend to general confusion and disorganization. –Good only on
Public API-
Journal Comments / History Tracker
Comments
Do not document the history in the comments area. That is what
source control is for.
Attributions and Bylines

/* Added by Rick */
Commented-Out Code
Do not comment junk
If you don't need anymore, please delete it, you can back later
with your VCS if you need it again.
Do not keep the code for the future, by commenting it.
Today we have source code control
systems, we don't need this type of
logs.
Noise Comments
The comments in the follow examples doesn't provides new
information.

Javadocs comments could enter in this category. Many times they


are just redundant noisy comments written out of some
misplaced desire to provide documentation.
Closing Brace Comments
You could break the code in small functions instead to use this
type of comments.
Don’t Use a Comment When You Can
Use a Function or a Variable

VS
Position Markers

This type of comments are noising


Artist Comment
You are allowed to be an artist, but not in the comments section.
Funny Comments
And so..
Nonlocal Information
If you must write a comment, then make sure it describes the
code it appears near. Don't offer systemwide information in the
context of a local comment.

Too Much Information


Don't put interesting historical discussions or irrelevant
descriptions of details into your comments.
And so..
Inobvious Connection
The connection between a comment and the code it describes
should be obvious. If you are going to the trouble to write a
comment, then at least you'd like the reader to be able to look at
the comment and the code and understand what the comment is
talking about

Function Headers
Short functions don’t need much description. A well-chosen name
for a small function that does one thing is usually better than a
comment header.

Javadocs in Nonpublic Code


Javadocs are for public APIs, in nonpublic code could be a
distraction more than a help.
Example
Example
Example - Refactored
Example - Refactored
Summary
Summarize
• Comments should be rare, and supposed to take our whole
attention, and readers should be glad it’s there.

• It should be a prerogative of a developer to write code that


expresses itself. In this light, comments can be seen as failures.

• Make it clear and up to date: Over time, comments


degenerate into lies because usually the code changes but the
comment does not.

• Comment bigger chunks of code


• Keep it short
Summarize
Worthwhile comment:
a. legal comments
b. informative comments (e.g., the format a regular
expression is trying to match)
c. TODO comments
d. public API comments
e. expression of intent comments
Summarize
Bad comments:
a. mumbling
b. redundant explanations
c. mandated redundancy
d. journal comments
e. big banner comments
f. closing brace comments
g. attribution comments
h. non-local comments

You might also like