Software engineering reading group clean code chapter 4
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

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 variable

  • Use banners like /* -----------ACTIONS ----*/ sparingly

Closing brace comments
Closing Brace Comments variable

  • 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 variable

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

  • 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 variable

  • 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 variable

Inobvious connection
Inobvious variable connection

Much better
Much better variable

Command query separation
Command Query Separation variable

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

  • 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 variable

  • 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 variable

  • 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 variable

  • 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? variable

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