Improving Code Review: Naming, Guiding Comments, and Communication Practices

Code review is a crucial practice for ensuring software quality in large‑scale development. High‑quality reviews not only raise code standards but also foster a positive team atmosphere, whereas low‑quality reviews can become mere formalities and even generate friction.

This article shares the author’s reflections on three often‑overlooked aspects of code review—naming, guiding comments, and communication—based on personal experience as a reviewer.

1. Naming

Effective naming follows a “U‑shaped” curve: beginners use vague names, experienced developers adopt descriptive names, and senior developers may relax a bit but still avoid ambiguous identifiers. The author illustrates poor naming with a simple example:

def get_var(u):
    """获取环境变量列表"""
    data1 = UserVarsManager.get(u)
    data2 = SiteVarsManager.get(u.site)
    return data1 + data2

After refactoring, the same logic becomes clearer:

def list_environment_vars(user):
    """获取环境变量列表"""
    items_user = UserVarsManager.get(user)
    items_site = SiteVarsManager.get(user.site)
    return items_user + items_site

Key recommendations:

Keep terminology consistent across the codebase (e.g., use env_vars or list_env_vars uniformly).

Avoid generic “manager” names; prefer more specific ones like UserEnvVariables or SiteEnvVariables .

2. Guiding Comments

Guiding comments supplement code by explaining the “why” rather than restating the “what.” They reduce the mental effort required to understand complex logic and help newcomers get up to speed faster.

Examples from Redis show how comments can clarify intent without adding new information, yet still improve readability:

/* Call the node callback if any, and replace the node pointer
   if the callback returns true. */
if (it->node_cb && it->node_cb(&it->node))
    memcpy(cp,&it->node,sizeof(it->node));

/* For "next" step, stop every time we find a key along the
   way, since the key is lexicographically smaller compared to
   what follows in the sub‑children. */
if (it->node->iskey) {
    it->data = raxGetData(it->node);
    return 1;
}

Common pitfalls to avoid:

Simply restating what the code does.

Chasing a high “comment‑to‑code” ratio without regard to quality.

Leaving outdated comments that mislead readers.

3. Communication Style

Code review is a collaborative activity, and the way feedback is delivered greatly influences its effectiveness. The author suggests:

Focus on the issue, not the person.

Tailor the tone to the reviewer’s experience level—be gentle with newcomers, concise with veterans.

Provide concrete examples or code snippets instead of long textual explanations.

Use respectful language to keep the discussion constructive.

For instance, instead of a blunt comment like “This loop is verbose, use a list comprehension,” a more helpful version would be:

Here the loop only filters and transforms items, which is a perfect case for a list comprehension. For example:
items = [to_item(obj) for obj in objs if obj.is_valid()]
Reference: https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions

Conclusion

The article summarizes the key take‑aways:

Continuously sharpen sensitivity to naming.

Maintain consistent terminology and replace generic names with precise ones.

Prioritize important domain‑specific names.

Guiding comments, while not adding new logic, significantly lower the cognitive load.

Avoid simple repetition, excessive comment density, and stale comments.

Encourage reviewers to request guiding comments for complex logic.

Effective communication is essential for a smooth review process.

By paying attention to these seemingly minor details, developers can markedly improve the quality of code reviews and, consequently, overall software quality.