WIP: Clean Code Best Practices

Owned by Nimisha Asthagiri (Deactivated)
Last updated: Mar 18, 2016

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