Code Words
When reviewing or otherwise talking about code, using objective words and phrases will make your feedback more actionable and less ambiguous. Some good ones include orthogonal, exhaustive, and implicitly dependent.
Avoid feedback that only contains words like clean, heavy, or unmaintainable. They’re subjective, and too often mean different things to different people. Using them is more likely to be met with a clarifying question rather than a change to the code.
Prefer words that reduce ambiguity and limit the possibility of misunderstood. What properties does the code exhibit that you are summarizing as “clean”? What problems does it have that make it “unmaintainable”? List those out and your critique is more likely to be well received and acted on.
Appendix: Vocabulary
- 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
- Components being arbitrarily grouped into a module. Ex. “utility” modules. 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.