Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Improving Code Readability

Jaime
June 10, 2012

Improving Code Readability

Simple presentation on improving code readability

Jaime

June 10, 2012
Tweet

More Decks by Jaime

Other Decks in Programming

Transcript

  1. P2P Code Academy Improving Code Readability 30th March

  2. None
  3. Why Should We Care • We Spent Most Of The

    Time on Maintenance • Written Once, Read Tens of Times • Messy Code Slows Us Down
  4. How to Achieve Readability • Golden Rule • Naming •

    Functions • Classes • Comments • Error Handling • [Code Smells and Heuristics]
  5. None
  6. Write code that is easy to understand

  7. Naming

  8. Use Intention Revealing Names • Names should reveal intent int

    d; int elapsedTimeInDays; int daysSinceCreation; int daysSinceModification;
  9. Avoid Disinformation int a = l; if ( O ==

    l ) a = O1; else l = 01; WTF?
  10. Avoid Encodings // pointer to zero-terminated string // array of

    floating-point values // array of unsigned long (systems) pszOwner; rgfpBalances; aulColors; Look For This in Our SourceCode
  11. Pick One Word Per Concept and Don’t Pun One Word

    = One Abstract Concept Fetch, Retrieve, Get Add, Insert, Append
  12. Meaningful Naming I • Use Intention-Revealing Names • Avoid Disinformation

    • Avoid Encodings • Pick One Word Per Concept and Don’t Pun
  13. Use Nouns For Classes and Verbs For Methods • User,

    Customer, Account • Login(), Whine(), Withdraw() • Use IsXXX or HasXXX for predicates if (jaime.HasDonuts()) people.Applaud();
  14. Use Solution Domain Names • Use Computer Science lingo –

    Algorithms – Data Structures – Design Patterns This is Sparta a Factory!!
  15. Use Problem Domain Names • Page, BlogPost, Category, Tag •

    Customer, Order, Account • Warrior, Warlock, Barbarian, Sorceress
  16. Add Meaningful Context sendMail(string addrStreet, string addrCity, string addrCountry); sendMail(Address

    address); public class Address { public string Street {get;set;} public string City {get;set;} public string County {get;set;} }
  17. Meaningful Naming II • Use Nouns for Classes • Use

    Verbs for Methods • Use Solution and Problem Domain Names • Add Meaningful Context
  18. Classes and Methods

  19. Methods I • Small • Do One Thing • DRY

    (Dont Repeat Yourself)
  20. Methods II • Avoid Flag Arguments • Wrap Logical Operations

    • Few Arguments or No Arguments
  21. Methods III • Avoid Output Arguments • Command/Query separation •

    One Level of Abstraction per Method
  22. Classes • Small – SRP (Single Responsibility Principle) – Strive

    for High Cohesion* koh-hee-zhuhn *
  23. GoodCode > BadCode + GoodComments

  24. Good Comments • Are Informative • Explain Intent • Clarify

    • Warn of Consequences • TODO
  25. Bad Comments • Redundant • Misleading • Journal Style •

    Commented Out Code i++; // increment i
  26. Don’t use a comment when you can use a function

    or a variable
  27. Error Handling • Prefer Exceptions to Returning Error Codes •

    Extract Try/Catch blocks – Error Handling is One Thing
  28. Be Awesome

  29. Check-in your code cleaner than when you checked it out

  30. EXERCISE IMPROVING READABILITY

  31. Exercise 01 • Can you understand what’s going on? •

    What problems do you see?
  32. Exercise 01 • Mine Sweeper game. • Game board =

    list of cells (theList) • Each cell simple array (int[]) • cell[0] is the status value of a cell • A status value of 4 means “flagged.” • Another Requirement? Think
  33. If you want to know more...

  34. If you want to know more...

  35. If you want to know more...

  36. References • Clean Code http://amzn.to/clean-code • The Art Of Readable

    Code http://amzn.to/art-of-readable-code • Refactoring: Improving The Design Of Existing Code http://amzn.to/refactoring-martin-fowler • Coding Horror: Code Smells http://bit.ly/coding-horror-code-smells
  37. Thank you

  38. Complete List of Code Smells and Heuristics reference material

  39. Smells and Heuristics

  40. Heuristics on Names • Choose Descriptive Names • Choose Names

    at the Appropriate Level of Abstraction • Use Standard Nomenclature Where Possible • Use Unambiguous Names • Use Long Names for Long Scopes • Avoid Encodings • Names Should Describe Side-Effects
  41. Smells on Comments • Inappropriate Information (i.e. Change history log)

    • Commented-Out Code • Comments that are: – Obsolete – Redundant – Poorly written
  42. Heuristics on Functions • Functions Should Do One Thing

  43. Smells on Functions • Too Many Arguments • Output Arguments

    [they are evil] • Flag Arguments (SRP++) • Dead Functions
  44. Heuristics on Logical Operations • Encapsulate Conditionals • Avoid Negative

    Conditionals
  45. General Heuristics • Vertical Separation • Use Explanatory Variables •

    Function Names Should Say What they Do • Follow Standard Conventions • Replace Magic Numbers With Named Constants • Don’t be Arbitrary
  46. General Smells • Duplication • Base Classes Depending on Their

    Derivatives • Too Much Information • Dead Code • Misplaced Responsibility
  47. General Smells II • Inconsistency • Clutter • Artificial Coupling

    • Feature Envy • Obscure Intent