software engineering reading group clean code chapter 4 n.
Skip this Video
Download Presentation
Software Engineering Reading Group: Clean Code Chapter 4

Loading in 2 Seconds...

play fullscreen
1 / 27

Software Engineering Reading Group: Clean Code Chapter 4 - PowerPoint PPT Presentation

  • Uploaded on

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

I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
Download Presentation

PowerPoint Slideshow about 'Software Engineering Reading Group: Clean Code Chapter 4' - quant

Download Now An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.

- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
software engineering reading group clean code chapter 4

Software Engineering Reading Group: Clean CodeChapter 4

Led by Nicholas Vaidyanathan

Lead Visionary, Visionary Software Solutions

  • 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
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
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
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
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
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
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
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
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
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.
position markers
Position Markers
  • Use banners like /* -----------ACTIONS ----*/ sparingly
closing brace comments
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
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
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
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
command query separation
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.
  • 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
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
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
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
how do you write functions like this
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!