Code Words

When talking about code, prefer words and phrases with concrete meanings. Some good ones are terms like orthogonal, exhaustive, and implicitly dependent. Use precise language to describe the properties of the code in question.

Avoid feedback that only contains words like clean, heavy, or unmaintainable without explaining your reasoning. What properties does the code exhibit that you are summarizing by describing it as “clean”? What problems does it have that make it unmaintainable? Terms with objective, well-defined meanings reduce ambiguity and limit the possibility of being misunderstood. Here are some example words that can be unclear in context:

• Easy is relative. What's easy for you is not easy for someone who hasn't worked on the same projects, used the same tools, or studied the same subjects.
• Clean is subjective. Saying clean is shorthand for a bundle of properties that you value. Your peers might bundle different properties under the same word. They might not even value the same things as you do. Listing the properties explicitly makes your feedback clearer and gives others the opportunity to disagree.

Appendix: Vocabulary

Here are some terms I use a lot when critiqueing designs and reviewing code.

Apparent dependency

Readily visible dependency between components, such as by explicit reference.

Change amplification

The number of places requiring modifcation in order to make a single logical change. Synonym for repetitiveness.

Cognitive load

How much someone needs to know in order to complete a task.

Cohesion

The degree to which components in a module belong together.

Coincidental cohesion

Degree of components grouped into a module arbitrarily. Ex. “utility” packages. See also cohesion.

Coupling

The degree of interdependence between components.

Exhaustive

All possibilities are handled.

Implicit dependency

A hidden relationship between components where one relies on another for its functionality without explicitly stating it.

Mutual dependency

A relationship between components where both rely on the other for their functionality. Synonym for circular dependency.

Orthogonal

Changing one component does not change another.

Rigorous

Both exhaustive and accurate.

Postscriptum: Priming your teammates

Using precise language is helpful when you’re the reviewer. When you’re on the other side as the author, you can make your changes more amenable to review by others.

Let teammates know what to expect well before you ask them to review your changes, as far in advance as you can. Ideally before you write too much code. That way, come review time, they’ll know what to expect. That reduces the risk that major edits will be needed, and limits apprehension toward starting a review.

Don’t surprise reviewers. Good ways to get them on their heels include:

• Dumping a refactor on them when they were expecting a bugfix
• Introducing a new design pattern for a routine change
• Implementing functionality in an unexpected location