STL: Consider new conventions for preprocessor comments
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 11.2k
- Forks
- 1.7k
- Avg merge
- 4d 15h
- Merged PRs (30d)
- 22
Description
We have a long-standing convention of commenting all preprocessor directives. This is extremely useful when preprocessor-controlled code is large and/or nested, because the comments clearly identify region boundaries. (This is even more important now that clang-format indents all preprocessor directives at 0.) Here's an example with large regions:
And nested regions:
But when preprocessor-controlled code is small (down to a single line) and non-nested, it starts looking silly, as @SuperWig observed in https://github.com/microsoft/STL/issues/340#issuecomment-559236933 :
In newer code, we sometimes use "arrow comments" to make regions even more visible, which is an improvement for large and/or nested scenarios as usual:
But similarly, it is generally silly for small non-nested scenarios (at least with simple conditions; the comments can be useful for complicated conditions even if the controlled code is small):
We should consider developing a simple set of rules for contributors to follow. Example suggestion:
- All
#elseand#endifdirectives should have arrow comments, - Except when the condition is simple, all of the controlled regions are a single line, and there is no nearby nesting.
That would require a bit of human judgement (what is "simple", what is "nearby"), but not very much.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the examples linked in stl/inc/functional, stl/inc/xstring, stl/inc/tuple, and stl/inc/vector, along with issue #340's comment. Compare the large, nested, and small preprocessor regions, then determine whether a consistent contributor convention can be agreed on; done means the convention is settled and recorded in the appropriate contributor guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100