Code Words
When talking about code in the context of software development, opt for 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. They usually mean different things to different people, so using them is more likely to get met with a clarifying question rather than a change to the code.
Relative words emphasize the experience gaps between the author and reviewer. Subjective words hazard the differences in their values.
- 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. Any two developers might have their own different definitions of “clean.” Instead of using clean as a shorthand summary judgment, try to think of the properties that you mean when you say clean and list them out. It makes your feedback clearer and gives others the opportunity to disagree.
Even words like simple or complex can be ambiguous so be sure to qualify what kind of complexity you mean.
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 feedback is more likely to be acted on.
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” 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.