software engineering reading group: clean code chapter 4
DESCRIPTION
Software Engineering Reading Group: Clean Code Chapter 4. Led by Nicholas Vaidyanathan http://www.nicholasvaidyanathan.info Lead Visionary, Visionary Software Solutions http://www.visionarysoftwaresolutions.com. Comments. Comments are not like Schindler’s List Comments are a necessary evil - PowerPoint PPT PresentationTRANSCRIPT
![Page 1: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/1.jpg)
Software Engineering Reading Group: Clean CodeChapter 4
Led by Nicholas Vaidyanathanhttp://www.nicholasvaidyanathan.infoLead Visionary, Visionary Software Solutionshttp://www.visionarysoftwaresolutions.com
![Page 2: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/2.jpg)
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
![Page 3: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/3.jpg)
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
![Page 4: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/4.jpg)
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
![Page 5: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/5.jpg)
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?
![Page 6: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/6.jpg)
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
![Page 7: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/7.jpg)
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
![Page 8: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/8.jpg)
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?
![Page 9: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/9.jpg)
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 obviousJavadocs – Truly useful
![Page 10: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/10.jpg)
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
![Page 11: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/11.jpg)
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.
![Page 12: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/12.jpg)
Don’t use a comment when you can use a function or a variable
![Page 13: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/13.jpg)
Position MarkersUse banners like /* -----------
ACTIONS ----*/ sparingly
![Page 14: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/14.jpg)
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
![Page 15: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/15.jpg)
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
![Page 16: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/16.jpg)
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.
![Page 17: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/17.jpg)
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
![Page 18: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/18.jpg)
TMI
![Page 19: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/19.jpg)
Inobvious connection
![Page 20: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/20.jpg)
Example of bad comments
![Page 21: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/21.jpg)
Much better
![Page 22: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/22.jpg)
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.
![Page 23: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/23.jpg)
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”?
![Page 24: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/24.jpg)
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
![Page 25: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/25.jpg)
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.
![Page 26: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/26.jpg)
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
![Page 27: Software Engineering Reading Group: Clean Code Chapter 4](https://reader035.vdocument.in/reader035/viewer/2022062218/56816122550346895dd0799e/html5/thumbnails/27.jpg)
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!