Updates for Code rules

[makortel]

The Code rules (http://cms-sw.github.io/cms_coding_rules.html) would benefit from some updates (list has been updated based on the discussion below)

• The links in the Table of Contents are broken (they have -- too much)
• Links to C++ Core Guidelines could updated to point to http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines instead of https://github.com/isocpp/CppCoreGuidelines
• Add SF.7: Don’t write using namespace at global scope in a header file from the C++ Core Guidelines under Section 7. (spurred by Addition of L1 tracking code for "TMTT" & (part of) "Hybrid" algorithms (L1Trigger/TrackFindingTMTT)  cmssw#29381 (comment))
• Add "Use std::abs() instead of fabs()"
• Add "Use C++ headers, e.g. #include <cmath> instead of #include math.h"
• Add "Do not use cout or cerr, use e.g. MessageLogger instead"
• Add "Use git versioning to retain old versions of code in the development history, rather than leaving commented-out code in files. if code is only commented out temporarily, a clear comment should be added describing why it's temporarily disabled and under what conditions it will be re-enabled."
• Add "Avoid const_cast"
• Relax 4.4. "Do not inline virtual functions." to "Do not inline virtual functions. (*) Allowed exception: inlining is permitted for simple functions like accessors and setters, as long as there is at least one non-inline virtual function in the class."
• Add "Avoid thread_local"

[makortel]

I was thinking to address these myself, but wanted to open an issue in the mean time.

[kpedro88]

while we're here, another informal rule should be formalized: use std::abs() not fabs()

maybe also: "use c++ headers like rather than c headers like <math.h>"?

[makortel]

Do the Core Guidelines say anything about either?

[kpedro88]

avoiding fabs is something we've recommended for a while to prevent undesirable type conversions (since c++11 improved std::abs())

i don't see anything about c++ vs c headers, but i think this is also something we commonly recommend

[makortel]

I know and agree, I was just wondering if the Core Guidelines would have a recommendation we could refer to (sorry I was unclear).

[smuzaffar]

For c vs c++ headers, although there is nothing in the Core guidelines but we force it via clang-tidy check https://clang.llvm.org/extra/clang-tidy/checks/modernize-deprecated-headers.html

[kpedro88]

i also notice that our ban on cout is not described in the code rules, this should definitely be added

[makortel]

i also notice that our ban on cout is not described in the code rules, this should definitely be added

It sort-of falls under 7.2 ("Ensure code is thread-safe"), but yes, it would be clearer to mention it explicitly.

Sounds like there is room for gather a bit more stuff and do one larger update (with a presentation in the core meeting and proper announcement of the update).

[kpedro88]

another one that I don't see explicitly in the rules:

• use git versioning to retain old versions of code in the development history, rather than leaving commented-out code in files. if code is only commented out temporarily, a clear comment should be added describing why it's temporarily disabled and under what conditions it will be re-enabled.

[kpedro88]

could also add "avoid const_cast"

[fwyzard]

Proposal: relax

Do not to inline virtual functions

to something like

Do not to inline virtual functions (*)

(*) inlining is permitted for simple functions like accessors and setters, as long as there is at least one non-inline virtual function in the class

[silviodonato]

Is it written somewhere about avoiding using namespace in header files?

[smuzaffar]

It is kind of part of original CMs coding huide lines document
https://cds.cern.ch/record/687032/files/note98_070.pdf

Use ‘using namespace’ only in local scope.

[makortel]

Is it written somewhere about avoiding using namespace in header files?

It is not part of our current code rules (although our tools flag it), which is why I'm suggesting to add it (from issue description

• Add SF.7: Don’t write using namespace at global scope in a header file from the C++ Core Guidelines under Section 7. (spurred by cms-sw/cmssw#29381 (comment))

)

[makortel]

Maybe we should add something about thread_local as well.