WIP: Clean Code Best Practices
This document is a collective summary of the best practices that the Clean Code book club recommends for open edX engineering.
Step Down Rule
Boy Scout Rule
Do One Thing Only
Include:
Comments
C1: Inappropriate Information
Comments should not include information better captured elsewhere.
C2: Obsolete Comments *
Get rid of or update ASAP
C3: Redundant Comments
C4: Poorly Written Comments
A comment worth writing is worth writing well. We value this enough to discuss comment quality in code review. Be kind to committers. Suggest documentation wording when appropriate.
C5: Commented out code
It should not be checked in. Delete it when you find it. (BSR)
Functions
F1: Too many arguments *
*kwargs
*zero?
F3: Boolean arguments
Not hard and fast rule
Use with kwargs, not positional.
F4: Dead functions
eliminate dead code.
General
G2: Obvious behavior is unimplemented
A function should do what callers would expect it to do
G3: Incorrect Behavior at the boundaries
Test your edge cases. Find a list of common error-causing edge values (zero, MAXINT, unicode chars)
G4: Overridden Safeties
Listen to your warnings. Make safe behavior the default.
G5: Duplication
G6: Code at the wrong level of Abstraction /G14: Feature Envy / Misplaced Responsibility (G17)
G7: Base Classes depending on their derivitives
Exception for constructors / factory methods
G8: Too much information (Large interfaces encourage too much coupling)
G9: Dead Code & Clutter (G12)
G10: Vertical separation (Keep related code close)
G11: Inconsistency
Our unit tests are often inconsistent. Maybe we could use more standards there?
G19: Use explanatory variables: Name an object rather than commenting.
G20: Good naming!
G22: Make logical dependencies physical *
G23: Prefer polymorphism to if/else or dispatch dictionaries
G25: Replace magic number s with named constants
G27: Structure over Convention
G30: Functions should do one thing *
Somewhat subjective but good advice
Ch 6: Objects vs data structures