P2148 Library Evolution Design Guidelines

[wg21bot]

P2148R0 Library Evolution Design Guidelines (CJ Johnson, Bryce Adelstein Lelbach)

[brycelelbach]

2021-01-19 Library Evolution Telecon

P2148R0: Library Design Guidelines

2021-01-19 Library Evolution Telecon Minutes

Chair: Bryce Adelstein Lelbach

Champion: CJ Johnson

Minute Taker: Ben Craig

Start: 2021-01-19 10:05 Pacific

Add front matter stating these are more like guidelines than rules; they can be
broken.

Can we even formulate guidelines and policies that will be consistent over time?

Should we have a naming policy for _t and _v suffixes? At least for type traits?

Maybe have a policy of not decorating name unnecessarily (we decided to avoid a decorate for concepts, for example).

Decorate as a last resort.

Name selection policy should be in this document.

Name selection policy: When there is debate over what something should be named, we will consider a set of candidate names for that thing; each candidate name must be justified with a paper.

Papers should always retain motivation/design/rationale, even when at the wording stage.

Papers should have a changelog.

We should reference/use the paper from Jonathan Mueller on naming concepts.

any_concept is a good starting place for a type-erased wrapper for a concept, but it's not a hard mandate; if there's a better name for it, use that name instead.

any_ wasn't useful for function wrappers because it didn't help you select between different similar things.

POLL: Suggest a naming pattern for type-erased wrappers for concepts.

Strongly Favor	Weakly Favor	Neutral	Weakly Against	Strongly Against
1	6	7	5	4

Attendance: 30

# of Authors: 1

Author Position: N

Outcome: No consensus, paper welcome but not necessarily encouraged.

Strike section 1.2.

For section 1.3, it would be good to list things in standard library that are consistent with this and things that are not consistent (empty on containers, valid on future).

Suggested phrasing of the is_ pattern: consider "is_" as candidate name when needing to disambiguate between "verb" and "noun" terms for a predicate function.

Add backstory/history to these policy decisions.

Function overloads should all do similar semantic things.

Constructors might be an exception to that.

Corentin and Ben will write a paper on this.

3.1 should clarify that it does not prescribe a general requirement on .size, it only prescribes a requirement on .size if the class has .data.

Perhaps require .size to be O(1) for things that have .data

3.1 increasingly sounds like a concept.

For 3.3, number each sub-bullet.

In 3.3 amend bullet 2 as "Each library function that LEWG and LWG agree cannot throw should be marked as unconditionally noexcept."

Strike 3.3 bullet 3.

3.3 bullet 4 should have some examples of wrapping types.

3.3 bullet 4 rephrase end of sentence.

End: 11:21

Summary

We reviewed P2148, Library Design Guidelines, which proposes the creation of a new standing document containing guidelines for the evolution of the Standard Library that Library Evolution as adopted. This paper doesn't propose new guidelines or policies; instead, it is a collection of various policies for Standard Library design that Library Evolution has previously adopted.

During our review of the paper, one thing that became apparent is that the next revision needs to incorporate links and references to the papers and minutes that it used for source material.

Much of our discussion revolved around the naming section. We seemed to have general agreement that we should not have any hard and fast rules here. If a naming guideline is applicable for the name of a certain entity, that does not mean the entity must follow that guideline; it just means that a name in accordance with the guideline should be one of the ones considered. We spent a lot of time talking about naming patterns in which a decorator prefix or suffix of some type (any_, _t, _v) should be used. We seemed to have a preference for doing this type of decoration only as a last resort when it is necessary for clarity.

We decided that the section proposing a naming pattern of any_C for a type erased wrapper for a concept C should be removed from the paper. We did not have consensus on the need for a a naming pattern for such type erased wrappers at all; to consider this further, we'd need a proposal exploring this topic.

We also discussed the possibility of using this standing document to describe some basic requirements for paper authors, like changelogs and retaining motivation/rationale/design once the paper has advanced to wording reviewing.

Finally, we asked the authors to incorporate the newly adopted procedure for selecting names in Library Evolution into the paper.

Outcome

Bring a revision of P2148R0 (Library Evolution Guidelines), with the guidance below, to Library Evolution for further review.

• Add more front matter clarifying that these are guidelines, not rules, and exceptions and deviation from them is acceptable when the situation merits it.
• Add references and links to the papers and minutes that established each of these policies
• Add our new naming procedures to section 1.
• Document "decorate as a last resort" in section 1.
• Remove section 1.2 which describes a naming pattern for type-erased wrappers for concepts.
• Add a new section on structural requirements for papers that documents that papers are expected to:
  • Retain motivation/design/rationale, even when at the wording stage.
  • Have a changelog.
• Update section 3 on exceptions to reflect the latest noexcept policies adopted by LEWG.