Sat
28
Sep 2019
Earlier this month I asked on Twitter "what is the weirdest and the most stupid rule you had to follow because of the "Coding Standard"?" I've got some interesting responses. Thinking about it more, I concluded that coding standards are complex. Having one in your project is a good thing because it imposes a consistent style, which is a value by itself. But specific rules are of various types. Some carry universally recognized good practices, like "use std::unique_ptr
, don't use std::auto_ptr
". Some serve good code performance, like "pass large structures as const&
parameters, not by value". Others are purely a matter of subjective preference of its authors, e.g. to use CamelCaseIdentifiers
rather than snake_case_identifiers
or spaces instead of tabs for indentation. Even the division between those categories is no clear though. For example, there is a research showing that Developers Who Use Spaces Make More Money Than Those Who Use Tabs.
But some rules are simply ridiculous and hard to explain in a rational way. Here are two examples from my experience:
Number 2: Lengthy ASCII-art comment required before every function. In that project we couldn't write an inline function even for the simplest getters, like:
class Element { private: int identifier; public: int GetIdentifier() { return identifier; } // Illegal!
We had to only declare member functions in the header file, while definition had to contain a specific comment that repeats the name of the function (which is a nonsense and a bad practice by itself, as it introduces duplication and may go out of sync with actual code), and its description (even if the name is self-descriptive), description of all its parameters (even if their names are self-descriptive), return value etc. Example:
/*****************************************************************************\ Function: Element::GetIdentifier Description: Returns identifier. Input: None. Output: Identifier of the current element. \*****************************************************************************/ int Element::GetIdentifier() { return identifier; }
I like comments. I believe they are useful to explain and augment information carried by function and variable names, especially when they document valid usage of a library interface. For example, a comment may say that a pointer can be null and what that means, a uint
may have special value UINT32_MAX
and what happens then, or that a float
is expressed in seconds. But the comment as shown above doesn't add any useful information. It's just more symbols to type, developer's time wasted, makes code bloated and less readable. It's not even in any standard format that could automatically generate documentation, like with Doxygen. It's just custom, arbitrary rule.
What was the reason behind this rule? A colleague once told me that many years ago the architect of this whole program hoped that they would develop a tool to parse all this code and those comments and generate documentation. Decades have passed, and it didn't happen, but developers still had to write those comments.
The effect was that everyone avoided adding new functions as much as possible or splitting their code into small functions. They were just adding more and more code to the existing ones, which could grow to hundreds of lines. That also caused one of the most obscure bugs I've met in my life (bug number 2).
Number 1: Don't use logical negation operator '!'
, like: if(!isEnabled)
. Always compare with false
instead, like: if(isEnabled == false)
.
I understand a requirement to always compare pointers and numbers to some value like nullptr
instead of treating them as booleans, although I don't like it. But banning one of the fundamental operators, also when used with bool
variables, is hard to justify for me.
Why would anyone come up with something like this? Is it because a single '!'
symbol is easy to omit when writing or reading and not so explicit as == false
? Then, if the author of this rule suffers from bad sight or dyslexia and a single dash here and there doesn't make a difference to him, maybe he should also define functions Add(), Subtract()
, and tell developers to use them instead of operators '+'
and '-'
, because they too are so easy to confuse? Or maybe not... He should rather go do something other than programming :)
Comments | #software engineering #c++ Share