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!