Programming rules and guidelines improve code consistency, but misapplication can lead to poor results. Arne Mertz suggests that software developers selectively adopt rules and guidelines, and document deviations with clear explanations. They can discuss their experiences in communities or during their daily work, to foster collaboration and improve code quality without unnecessary bureaucracy.
Arne Mertz gave a talk about programming rules and guidelines at NDC Tech Town.
Programming rules and guidelines help developers work together, which can result in more consistent and better code. However, using them the wrong way can have the opposite result - code that is cumbersome to read or solves problems in suboptimal or even wrong ways, as Mertz explained in the InfoQ article how to use programming rules and guidelines.
As an example, Mertz mentioned the C++ Core Guideline don’t make data members const or references in a copyable or movable type. The second part gets omitted quite often but is important, as he explained:
A const member can not be reassigned, a reference member can not be directed to refer to something else, so a type with this kind of member can not be assigned to normally. The compiler will not be able to generate move and copy assignment operators for these types. Therefore, these members should not be used in types that are designed to have value semantics.
While these types usually make up a large part of an application’s types, there are others that do not have value semantics, Mertz said. He mentioned application services and repositories as examples. For these latter types, it is perfectly acceptable and normal to have reference members, Mertz said.
Mertz suggested thinking about which guidelines to adopt, and how to document them. A 50-page Word document tucked away in some SharePoint page is rarely read, he mentioned. Developers will not know and therefore ignore most of the guidelines in there.
Many guidelines can be checked automatically, e.g. using clang tidy, but then we need a way to turn warnings off in specific cases, because, after all, guidelines are not rules, Mertz said.
Mertz mentioned that they have an active C++ community in their company where they exchange their experiences in different projects. More experienced developers support their colleagues by answering questions and giving advice, he explained:
We have a C++ example project with a typical clang-tidy file to provide some sensible defaults for automatic checks of the C++ Core Guidelines and more.
Mertz mentioned they sometimes discuss the customer’s guideline document in their weekly developer sync. But they also come up with their own, more specific guidelines when they find they need them:
The process is pragmatic and not too formal, but we found that over time that leads to more consistent and higher quality code without the overhead of bureaucracy.
Part of these meetings could be seen as a "technical retrospective" where they discuss what works best for them and how to avoid pitfalls that they came across in their specific code base, Mertz concluded.
InfoQ interviewed Arne Mertz about coding rules and guidelines.
InfoQ: How do rules and guidelines differ from each other?
Arne Mertz: A rule is more or less absolute, it has to be followed wherever it applies. A guideline is a best practice or sensible default, people may diverge and that’s OK. Since guidelines are not rules, I suggest documenting when you deliberately do not follow a guideline, e.g. with a comment explaining the reasons.
Rules are convenient - we, or our automatic tools, can just point to them and say "wrong", and we have to fix our code. Guidelines give more freedom, but also more responsibility - we cannot simply follow them on auto pilot. Yet, they are an important tool.
InfoQ: What benefits can software development teams get from using guidelines?
Mertz: When a team follows common guidelines, we know what to expect from code. The "Principle of Least Surprise" is an important design principle that makes code easier to read and understand.
Even as a reader of code, knowing the guidelines it follows is useful: if a reader is familiar with coding guidelines and writing conventions in general, it is easier to spot unconventional code that might need a closer look.
About the Author
