Software Engineering Reading Group: Clean CodeChapter 4
Led by Nicholas Vaidyanathanhttp://www.nicholasvaidyanathan.infoLead Visionary, Visionary Software Solutionshttp://www.visionarysoftwaresolutions.com
CommentsComments 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 WordsEvery 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
mish-mashed 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 noneInaccurate 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 longerTruth can be found in only one
place: the code
Comments Do Not Make Up For Bad CodeClear and expressive code with
few comments is far superior to cluttered and complex code with lots of comments
Explain yourself in codeIt 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 commentsLegal commentsInformative comments
◦ Can usually be replaced with cleaner codeExplanation of Intent
◦ Can help rationalize seemingly odd decisionsClarification
◦ Risky, can be difficult to verifyExplanation of ConsequencesTODO CommentsAmplification
◦ 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 BadMandated 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 MarkersUse 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 informationDon’t put information in places
where it may not be relevantDon’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 SeparationFunctions 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 CodesReturning 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 YourselfDuplication 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 ProgrammingEdsger 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!