Cppcoreguidelines: The entirety of "NL: Naming and layout rules" should be removed

[JamesMcNellis]

The C++ Core Guidelines contain a lot of great advice for C++ programmers that can help them to write substantially better, safer, more correct, and more efficient C++ code. Advice on things like how to pass parameters efficiently, how to use smart pointer types to control ownership, how (not) to mix signed and unsigned types in arithmetic, and how to write const-correct code. There is a lot of content of great value to C++ programmers at all skill levels, and the fact that some of the rules can (at least in theory) be checked via static analysis makes these rules doubly good.

However, mixed in with these excellent rules, are what I would refer to as _frivolous_ rules. Advice on things like what brace style to use, how to capitalize enumerator names, or where to place the const keyword. The C++ Core Guidelines has become a jumble of excellent advice that will lead to better code, and rules about things that really, truly, in a million years do not matter.

When reading the C++ Core Guidelines, one ends up wondering “is this one of the important rules, or is this another one of the frivolous rules?” Or, if one wants to make reference to the C++ Core Guidelines to defend a position in a code review, that reference drags along with it all of the baggage of these other rules that are highly contentious and about which there is great disagreement. The value of the C++ Core Guidelines as a whole is substantially diluted by the presence of these frivolous rules.

The entire NL section is inconsistent with, and a distraction from, the goal to provide “Core” Guidelines. I recall the very first item (Item #0) from Herb Sutter’s and Andrei Alexandrescu’s _C++ Coding Standards_ explicitly excluded discussing such things as unworthy of an industry-wide coding standard. “Don’t sweat the small stuff. (Or: Know what not to standardize.)”

The C++ Core Guidelines would be of far greater value if they focused on the things that truly matter—rules that truly lead to higher-quality, safer, more correct, more efficient code. To that end, I would strongly recommend _removal_ of the entire NL section. The C++ Core Guidelines currently weigh in at 503 pages. Editors, please remember that editing includes removing the parts that you might love, but which really don’t belong.

(I think it would be quite reasonable to move these rules into a separate document, as a proposed C++ coding style to follow. The C++ Core Guidelines is just the wrong place for these rules.)

[Prior issue #1186 suggested removal of some of the NL rules and alteration of others.]

[timangus]

Mmmm, always felt CPPCG has parts that read like the formatting section of a coding standard. Not really the place for that kind of thing IMO.

[cubbimew]

This issue is now also discussed on reddit

[NicolBolas]

I understand your general disdain for text conventions that do not directly affect the quality of the executable code. However, good code is about more than just the quality of the compiled binary. Readability of code is of paramount concern when it comes to writing good code. How items are named and how code is structured affects readability. So it makes sense that the guidelines should weigh in on the topic.

The core guidelines should be treated as exactly that: guidelines, not rules. Take those that make sense, and leave those that don't.

[JamesMcNellis]

@NicolBolas To the contrary, I agree wholeheartedly that consistency of style within a codebase improves code readability and is thus a critical component of overall code quality.

My objection to inclusion of naming and layout rules in the C++ Core Guidelines is that (1) there is zero consensus as to what style should be recommended by the C++ Core Guidelines, and (2) the work required to come to consensus would outweigh the value of trying to build consensus by orders of magnitude (I would argue that coming to consensus on such matters is, in fact, impossible. See, for example, the ongoing and eternal debate over "const west" vs. "east const").

[brenoguim]

@JamesMcNellis The very first paragraph on NL goes:

Consistent naming and layout are helpful. If for no other reason because it minimizes "my style is better than your style" arguments. However, there are many, many, different styles around and people are passionate about them (pro and con). Also, most real-world projects includes code from many sources, so standardizing on a single style for all code is often impossible. We present a set of rules that you might use if you have no better ideas, but the real aim is consistency, rather than any particular rule set.

It acknowledges there are multiple styles and no consensus. Consensus is not required.

That first paragraph is very clear that consistency in the codebase is the most important thing, and the NL section goes to exemplify what would be one possible style.

[hsutter]

That first paragraph is very clear

You are correct, but one of the problems we've discovered is that people keep missing that first sentence because "These rules are not meant to be read serially, like a book ... their main intended use is to be targets for tools [that link] to violated rules."

So people keeping getting links to deep within NL, don't see the intro and caveats several pages above it, and so don't realize that this is one of the 'not-Core' items in the Core Guidelines document.

[brenoguim]

Fair point. It's reasonable to move it to a separate place then. The core guidelines could maybe mention the importance of keeping consistency regardless of the style, and provide a link to the style suggestion/example.

[hsutter]

Editors discussion: We understand, and our current thought is to maybe add a one-line disclaimer to each NL guideline "remember, this is a recommendation if you have no better ideas, this section was added after a number of requests for default style guidance" with a link to the longer overall disclaimer at the top of the section.

[BjarneStroustrup]

Closed after applying the editors recommendations