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

Improving Code Readability

June 10, 2012

Improving Code Readability

Simple presentation on improving code readability


June 10, 2012

More Decks by Jaime

Other Decks in Programming


  1. Why Should We Care • We Spent Most Of The

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

    Functions • Classes • Comments • Error Handling • [Code Smells and Heuristics]
  3. Use Intention Revealing Names • Names should reveal intent int

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

    l ) a = O1; else l = 01; WTF?
  5. 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
  6. Pick One Word Per Concept and Don’t Pun One Word

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

    • Avoid Encodings • Pick One Word Per Concept and Don’t Pun
  8. 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();
  9. Use Solution Domain Names • Use Computer Science lingo –

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

    Customer, Order, Account • Warrior, Warlock, Barbarian, Sorceress
  11. 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;} }
  12. Meaningful Naming II • Use Nouns for Classes • Use

    Verbs for Methods • Use Solution and Problem Domain Names • Add Meaningful Context
  13. Error Handling • Prefer Exceptions to Returning Error Codes •

    Extract Try/Catch blocks – Error Handling is One Thing
  14. 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
  15. 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
  16. 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
  17. Smells on Comments • Inappropriate Information (i.e. Change history log)

    • Commented-Out Code • Comments that are: – Obsolete – Redundant – Poorly written
  18. Smells on Functions • Too Many Arguments • Output Arguments

    [they are evil] • Flag Arguments (SRP++) • Dead Functions
  19. 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
  20. General Smells • Duplication • Base Classes Depending on Their

    Derivatives • Too Much Information • Dead Code • Misplaced Responsibility