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 should not include information better captured elsewhere.
Get rid of or update ASAP
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.
It should not be checked in. Delete it when you find it. (BSR)
*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