Chapter 4

Software Engineering Reading
Group: Clean Code
Chapter 4
Led by Nicholas Vaidyanathan
Lead Visionary,Visionary Software Solutions
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
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
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
◦ Risky, can be difficult to verify
Explanation of Consequences
TODO Comments
◦ 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
◦ 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
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
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
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
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.
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
◦ 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
◦ 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!

similar documents