Software Engineering Reading
Group: Clean Code
Chapter 4
Led by Nicholas Vaidyanathan
http://www.nicholasvaidyanathan.info
Lead Visionary,Visionary Software Solutions
http://www.visionarysoftwaresolutions.com
Comments

Comments are not like Schindler’s List
◦ Comments are a necessary evil

The proper use of comments is to
compensate for our failure to express
ourselves in code
◦ Comments are always failures
Harsh Words
Every time you express yourself in code,
you should pat yourself on the back.
 Every time you write a comment, you
should grimace and feel the failure of your
ability of expression

Why the hate?

Comments lie
◦ The older the comment is, the farther away it
is from the code it’s meant to explain, the
more likely it is wrong

Code changes and evolves
◦ Constantly moving around, being mishmashed together in odd places
Programmer’s fault!

Shouldn’t programmers be disciplined
enough to maintain comments in a high
state of repair, relevancy, and accuracy?

Wouldn’t that energy be better spent
making the code so expressive that
comments were unnecessary?
Sometimes some is worse than
none

Inaccurate comments are worse than no
comments at all
◦ Delude and mislead
◦ Set expectations that are left unfulfilled
◦ Lay down old rules that need not or should
not be followed any longer

Truth can be found in only one place: the
code
Comments Do Not Make Up For
Bad Code

Clear and expressive code with few
comments is far superior to cluttered and
complex code with lots of comments
Explain yourself in code

It takes only a few seconds of thought to
explain most of your intent in code. In
many cases it’s simply a matter of creating
a function that says the same thing as the
comment you want to write.

Which would you rather see?
Good comments


Legal comments
Informative comments
◦ Can usually be replaced with cleaner code

Explanation of Intent
◦ Can help rationalize seemingly odd decisions

Clarification
◦ Risky, can be difficult to verify



Explanation of Consequences
TODO Comments
Amplification
◦ Can make seemingly inconsequential more obvious

Javadocs – Truly useful
Bad Comments
◦ Mumbling
 Any comment that forces you to look in another
module for the meaning of that comment has failed
to communicate to you and is not worth the bits it
consumes
◦ Redundant information
◦ Misleading comments
More Bad

Mandated comments
◦ Clutter up code with unnecessary redundancy

Journal comments
◦ Better put in source control logs

Noise comments
◦ Add no new useful information
◦ Replace the temptation to create noise with
the determination to clean your code.You’ll
find it makes you a better and happier
programmer.
Don’t use a comment when you can
use a function or a variable
Position Markers

Use banners like /* -----------ACTIONS
----*/ sparingly
Closing Brace Comments
◦ Only makes sense for long functions with
deeply nested functions
◦ …BUT
◦ We don’t like long functions with deeply
nested structures….
◦ …SO
◦ If you find yourself wanting to mark your
closing braces, try to shorten your functions
instead
Commented out code
Few practices are as odious as
commenting-out code. Don’t do this!

◦

Others who see the code won’t have the
courage to delete it. They’ll think it’s there
for a reason and is too important to delete.
Commented-out code gathers like the
dregs at the bottom of a bad bottle of
wine
Use Source Control!
There was a time, back in the sixties,
when commenting-out code might have
been useful…
 But we’ve had good source code control
systems for a very long time now. Those
systems will remember the code for us.
We won’t lose it. Promise.

Nonlocal information
Don’t put information in places where it
may not be relevant
 Don’t put information about expected
values of a function that are beyond that
function’s control

TMI
Inobvious connection
Example of bad comments
Much better
Command Query Separation

Functions should either do something or
answer something, but not both.
◦ Either your function should change the state
of an object, or it should return some
information about that object.
◦ Doing both often leads to confusion.
Separate!
public boolean set(String
attribute, String value);
 if (set("username", "unclebob"))...

◦ Is it asking whether the “username” attribute
was previously set to “unclebob”?
◦ is it asking whether the “username” attribute
was successfully set to “unclebob”?
Prefer Exceptions to returning
Error Codes

Returning error codes is a subtle violation of
Command Query Separation
◦ Promotes commands being used as predicates in
if statements, leading to deep nesting

Extract try/catch blocks

Error Handling is One Thing
Don’t Repeat Yourself

Duplication is a problem
◦ Requires modification in multiple places on
changes..lots of opportunity for error

Duplication may be the root of all evil in
software.
◦ Many principles and practices have been
created for the purpose of controlling or
eliminating it.
Structured Programming

Edsger Djikstra Rules
◦ Every function and every block within a
function should have one entry and one exit
◦ Only 1 return statement
◦ No break or continue in loops
◦ Never any gotos
How Do You Write Functions
Like This?

Writing software is like any other kind of
writing
◦ When you write a paper or an article,you get
your thoughts down first, then you massage it
until it reads well.
◦ Refactor, Refactor, Refactor!
◦ But write Unit Tests that stress the original
first, and keep them passing!