Software Engineering Reading Group: Clean Code Chapter 4 Led by Nicholas Vaidyanathan Lead Visionary, Visionary Software Solutions

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 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 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!