4 ms·
After quite a few decades' experience with style guides, I have determined that they are vastly over-valued, and often very actively harmful. There are three m
by ncmncm 6y ago
After quite a few decades' experience with style guides, I have determined that they are vastly over-valued, and often very actively harmful.
There are three major problems with typical style guides (including yours):
1. Triviality
They legislate behaviors that are easy to express and police, but don't actually result in better code. This is a big evil because it distracts from hard-learned behaviors that do make better code.
Programmer attention is the scarcest resource any of us have. Almost all bugs trace to a lapse somewhere. Hence, anything that squanders attention actively generates bugs. Lining up columns generates bugs.
How often have you got review notes that mentioned nothing but style trivialities? Did the reviewer have attention to spare for things that will matter?
2. Obsolescence
Style guides are invariably obsolete on their first day, and only get worse. Updating a style guide is always contentious, rightly recognized as a waste of senior engineers' time, yet not to be trusted to their juniors. So, the guide is for a language as it might have been used (somewhere) five, ten, 20 years ago. Current best practices are not mentioned at all.
Worse, if it ever is updated, none of the existing code conforms anymore. Nobody is so foolish as to try to bring all old code up to new requirements. Automated updates can only address trivial changes. So, you have an official style that is either badly out of date, or at best doesn't match the code you have.
3. More obsolescence
Besides the style guide's own obsolescence, it legislates code constructs that are obsolete. "This is why we can't have nice things." Each bit of new code that conforms to the old guide for bad or trivial reasons amounts to more tech debt.
Ultimately, there is no substitute for competence. Good engineers will not write hard-to-read code. Somebody who does will, despite the best guide. Your only hope is to demand competence.
Instead
What can we do, then, to avoid chaos?
First, instead of mandating trivialities, identify principles and goals. Refer to concrete benefits to code quality. Good principles will address very different topics than your style guide did. Structs should have not too many members, functions limited size, names be (only) long enough to be readily distinguished from others, whitespace draw attention to places that need it, not wasted on highlighting nothings. The principles are based on psychology and the limits of attention, not typography.
Consistency is good in small amounts, and harmful in the large. When there are old ways and a new way of doing things, people reading code can easily adjust to each where it appears, recognizing that old code is that way because it is old. Changing habits become a useful marker of code origin.
The useful range for consistency is not a project, or folder, or file. It is at most 20 lines.
- goto11 6y agoIMHO code guidelines are there to avoid wasting time on trivialities. Why would something which is already settled by the guidelines even crop up code reviews, except for the first few commits from a junior developer? Lots of style choices are more or less arbitrary. PascalCase or camelCase? Big endiand or little endian? Comments and identifiers in english or french? You cant just "demand competence" because neither is clearly superior. But consistency is clearly superior to everyone doing it their own way. So you make a decision, write it down in a guide, and the question will not take up any more time and attention. But yeah, a guideline which legislates obsolete code constructs is obviously bad. Clearly something is deeply wrong in the culture of the team if the guideline is 20 years out of data and no one care about updating it - while at the same wastes a lot of resources on pointing out the issues in code reviews! But that problem is not with guidelines per se. Using an obsolete compiler will probably also give you problems.