@perry, you asked the following question (I edited it a bit to resolve some ambiguity):
"When writing [code] with an updated style, is the author [of that code] responsible for updating all local (say, within the current file) violations? Extra work that's not necessarily relevant to the bug at hand, but makes subsequent reading more consistent."
I would say that the author is not obliged but encouraged to do so, time permitting. Whether that's the case depends on the size of the file, the number of violations and the complexity and risk of performing the changes, which can be left to the judgment of the code author IMO.
I will include this in the description of the evolution process, maybe in some FAQ section.
You also made some suggestions for the content:
- prefer const/constexpr over macros: This is already mentioned in the Google C++ coding style at https://google.github.io/styleguide/cppguide.html#Preprocessor_Macros
- strongly typed enums (i.e. scoped enums) over old enums: I will create a bug to include this in our style.
- no 200 line functions: The Google C++ coding style encourages "short" functions at https://google.github.io/styleguide/cppguide.html#Write_Short_Functions, but does explicitly not mention a particular length. I would make this a bit stricter. A hard limit cannot be set, probably. But a soft limit of much less than 200 lines (maybe 40 lines?) would be good, encouraging the author/reviewer to seriously reconsider if something should be done about the length of the function in that case. I will create a bug to include a rule related to this in our style.
- comments where needed: This is already mentioned in the Google C++ coding style at https://google.github.io/styleguide/cppguide.html#Comments (Comments are absolutely vital to keeping our code readable. The following rules describe what you should comment and where. But remember: while comments are very important, the best code is self-documenting. Giving sensible names to types and variables is much better than using obscure names that you must then explain through comments.)
- well-defined order for #includes: The Google C++ coding style defines an order for includes at https://google.github.io/styleguide/cppguide.html#Comments. As you mention, clang-format can be configured to automatically order and group includes (at least where they are not conditional). However, applying this ubiquitously and/or automatically requires self-contained headers, which we reportedly do not have everywhere (I am not sure where such exceptions are, and if they are relevant to our modules).
- class structure public/protected/private: This is already mentioned in the Google C++ coding style at https://google.github.io/styleguide/cppguide.html#Declaration_Order (second paragraph)
It might be helpful to explicitly reinforce points particular important to us (or which are often neglected) that are already covered by the Google C++ Coding Style (with a reference to that style).
@perry, please briefly acknowledge here that I address your feedback as intended, or comment on what I got wrong. Thanks!