P2P Code Academy
Improving Code Readability
30th March
Slide 2
Slide 2 text
No content
Slide 3
Slide 3 text
Why Should We Care
• We Spent Most Of The Time on Maintenance
• Written Once, Read Tens of Times
• Messy Code Slows Us Down
Slide 4
Slide 4 text
How to Achieve Readability
• Golden Rule
• Naming
• Functions
• Classes
• Comments
• Error Handling
• [Code Smells and Heuristics]
Slide 5
Slide 5 text
No content
Slide 6
Slide 6 text
Write code that is easy
to understand
Slide 7
Slide 7 text
Naming
Slide 8
Slide 8 text
Use Intention Revealing Names
• Names should reveal intent
int d;
int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
Slide 9
Slide 9 text
Avoid Disinformation
int a = l;
if ( O == l )
a = O1;
else
l = 01;
WTF?
Slide 10
Slide 10 text
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
Slide 11
Slide 11 text
Pick One Word Per Concept and
Don’t Pun
One Word = One Abstract Concept
Fetch, Retrieve, Get
Add, Insert, Append
Slide 12
Slide 12 text
Meaningful Naming I
• Use Intention-Revealing Names
• Avoid Disinformation
• Avoid Encodings
• Pick One Word Per Concept and Don’t Pun
Slide 13
Slide 13 text
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();
Slide 14
Slide 14 text
Use Solution Domain Names
• Use Computer Science lingo
– Algorithms
– Data Structures
– Design Patterns
This is Sparta a Factory!!
Slide 15
Slide 15 text
Use Problem Domain Names
• Page, BlogPost, Category, Tag
• Customer, Order, Account
• Warrior, Warlock, Barbarian, Sorceress
Slide 16
Slide 16 text
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;}
}
Slide 17
Slide 17 text
Meaningful Naming II
• Use Nouns for Classes
• Use Verbs for Methods
• Use Solution and Problem Domain Names
• Add Meaningful Context
Slide 18
Slide 18 text
Classes and Methods
Slide 19
Slide 19 text
Methods I
• Small
• Do One Thing
• DRY (Dont Repeat Yourself)
Slide 20
Slide 20 text
Methods II
• Avoid Flag Arguments
• Wrap Logical Operations
• Few Arguments or No Arguments
Slide 21
Slide 21 text
Methods III
• Avoid Output Arguments
• Command/Query separation
• One Level of Abstraction per Method
Slide 22
Slide 22 text
Classes
• Small
– SRP (Single Responsibility Principle)
– Strive for High Cohesion*
koh-hee-zhuhn
*
Slide 23
Slide 23 text
GoodCode > BadCode + GoodComments
Slide 24
Slide 24 text
Good Comments
• Are Informative
• Explain Intent
• Clarify
• Warn of Consequences
• TODO
Slide 25
Slide 25 text
Bad Comments
• Redundant
• Misleading
• Journal Style
• Commented Out Code
i++; // increment i
Slide 26
Slide 26 text
Don’t use a comment
when you can use
a function or a variable
Slide 27
Slide 27 text
Error Handling
• Prefer Exceptions to Returning Error Codes
• Extract Try/Catch blocks
– Error Handling is One Thing
Slide 28
Slide 28 text
Be Awesome
Slide 29
Slide 29 text
Check-in your code cleaner
than when you checked it out
Slide 30
Slide 30 text
EXERCISE
IMPROVING READABILITY
Slide 31
Slide 31 text
Exercise 01
• Can you understand what’s going on?
• What problems do you see?
Slide 32
Slide 32 text
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
Slide 33
Slide 33 text
If you want to know more...
Slide 34
Slide 34 text
If you want to know more...
Slide 35
Slide 35 text
If you want to know more...
Slide 36
Slide 36 text
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
Slide 37
Slide 37 text
Thank you
Slide 38
Slide 38 text
Complete List of
Code Smells
and
Heuristics
reference material
Slide 39
Slide 39 text
Smells and Heuristics
Slide 40
Slide 40 text
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
Slide 41
Slide 41 text
Smells on Comments
• Inappropriate Information (i.e. Change history log)
• Commented-Out Code
• Comments that are:
– Obsolete
– Redundant
– Poorly written
Slide 42
Slide 42 text
Heuristics on Functions
• Functions Should Do One Thing
Slide 43
Slide 43 text
Smells on Functions
• Too Many Arguments
• Output Arguments [they are evil]
• Flag Arguments (SRP++)
• Dead Functions
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
Slide 46
Slide 46 text
General Smells
• Duplication
• Base Classes Depending on Their Derivatives
• Too Much Information
• Dead Code
• Misplaced Responsibility
Slide 47
Slide 47 text
General Smells II
• Inconsistency
• Clutter
• Artificial Coupling
• Feature Envy
• Obscure Intent