Software Engineering Reading Group: Clean Code Chapter 4

1. Software Engineering Reading Group: Clean CodeChapter 4 Led by Nicholas Vaidyanathan http://www.nicholasvaidyanathan.info Lead Visionary, Visionary Software Solutions http://www.visionarysoftwaresolutions.com

2. 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

3. 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

4. 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

5. 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?

6. 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

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

8. 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?

9. 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

10. 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

11. 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.

12. Don’t use a comment when you can use a function or a variable

13. Position Markers • Use banners like /* -----------ACTIONS ----*/ sparingly

14. 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

15. 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

16. 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.

17. 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

18. TMI

19. Inobvious connection

20. Example of bad comments

21. Much better

22. 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.

23. 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”?

24. 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

25. 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.

26. Structured Programming • EdsgerDjikstra 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

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