Improving Code Readability

1dfad8107453e0f493ff1a6a8e48d503?s=47 Jaime
June 10, 2012

Improving Code Readability

Simple presentation on improving code readability

1dfad8107453e0f493ff1a6a8e48d503?s=128

Jaime

June 10, 2012
Tweet

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