microsoft / microsoft/STL

STL: Consider new conventions for preprocessor comments

Open
#351 14 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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:

https://github.com/microsoft/STL/blob/1d39dfac9929c0d3c405edf6bc7eff26bbe2a26b/stl/inc/functional#L1228-L1250

And nested regions:

https://github.com/microsoft/STL/blob/1d39dfac9929c0d3c405edf6bc7eff26bbe2a26b/stl/inc/xstring#L295-L306

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 :

https://github.com/microsoft/STL/blob/1d39dfac9929c0d3c405edf6bc7eff26bbe2a26b/stl/inc/functional#L866-L870

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:

https://github.com/microsoft/STL/blob/1d39dfac9929c0d3c405edf6bc7eff26bbe2a26b/stl/inc/tuple#L259-L284

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):

https://github.com/microsoft/STL/blob/1d39dfac9929c0d3c405edf6bc7eff26bbe2a26b/stl/inc/vector#L691-L695

We should consider developing a simple set of rules for contributors to follow. Example suggestion:

  • All #else and #endif directives 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.