microsoft / microsoft/STL

STL: Consider cleaning up and numbering static_assert messages

Open
#209 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
C++
Stars
11.1k
Forks
1.7k
Avg merge
4d 15h
Merged PRs (30d)
22

Description

MSVC's compiler warnings and errors are numbered. Somewhat recently, we started numbering the STL's deprecation warnings. These unique numbers are searchable (and can be documented, in theory):

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/yvals_core.h#L676-L681

However, we haven't been numbering our static_assert messages. We have two numbered #error messages, and that's it:

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/yvals_core.h#L425-L431

Our static_assert messages are sometimes detailed:

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/type_traits#L22-L24

And sometimes not:

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/type_traits#L1464-L1466

We should consider cleaning up our static_assert messages to be uniformly detailed (with Standardese citations when possible), and numbering them. The questions that we need to answer are:

  • What numbers should we use? My initial thought is to continue imitating the compiler:
    • STL1000 series for fatal errors (e.g. using an intolerably old compiler is a configuration error that needs to be fixed before dealing with anything else)
    • STL2000 series (eventually STL3000 series) for ordinary errors
    • STL4000 series (eventually STL5000 series) for warnings
  • How do we ensure that numbers are uniquely used, and never reused? For warnings, we follow the conventions:

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/yvals_core.h#L507

https://github.com/microsoft/STL/blob/6b0238d7035236af0f81917262691db701e70fe3/stl/inc/yvals_core.h#L833

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

Start by comparing the numbered deprecation warnings and #error messages in stl/inc/yvals_core.h with the static_assert messages in stl/inc/type_traits. Determine a numbering scheme and how uniqueness and non-reuse should be maintained. Done means the project has agreed conventions for uniformly detailed, appropriately numbered static_assert messages.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
developer-experience, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.