Improving Code Readability

Simple presentation on improving code readability

Transcript

1. P2P Code Academy Improving Code Readability 30th March
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]
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