Open CaseyCarter opened 5 years ago
Editorial meeting:
Thanks! Could you paste this list into the wiki, too?
Some rationale from the discussion: We don't want to ban any sort of alignment outright, nor do we want a hard rule for when to align. Alignment is a tool, and we should use it with good judgement. We agree that it should not be overused, and we have come up with a number of specific constraints and principles:
Itemdecls should never use "out-of-context" alignment, i.e. alignment that would only make sense in the context of the corresponding synopsis. (When an itemdecl contains multiple declarations, they may retain alignment that's locally useful.) Moreover, the declaration in a synopsis should be formatted the same as in any itemdecl that repeats it.
Alignment is sometimes useful: It can help isolate the declared name amidst a sea of keywords and right-hand-sides, and it can help to emphasize small differences in long passages that share large common subsets.
The "Rules" Jens mentions above limit the number of places where we can insert aligning whitespace, so as to keep the number of presentational variations small that readers are confronted with. Moreover, they ensure that any blocks of code that do use alignment are sufficiently separated from ambient code to have local consistency without creating large-scale "blocking" or "staircasing".
We considered the historic practice of aligning function names (e.g. "erase" and "insert") excessive and don't condone this in the future. (Cleanup PRs for existing synopses are welcome.)
In summary, within reason we can use alignment where it improves the overall presentation. Do feel free to address specific, focused instances via issues or pull requests where you feel that we can make improvements.
Rules added to the wiki.
Declarations in library header and class synopses often go to great lengths to add spaces to align declarations in various ways. We're inconsistent about when we do so, and how we do so. These hand-alignments are fragile, and result in weird "stairsteps" between regions of local consistency. We should establish a consistent policy for which declarations, if any, we align.
Some examples drawn from [utilities]:
[allocator.traits]: