dotnet / dotnet/csharpstandard

Consider reordering and reorganizing sections

Open
#959 16 comments 0 reactions 3 assignees Claimed by @RexJaeschke View on GitHub
Dominant language
C#
Stars
815
Forks
99
Avg merge
1d 14h
Merged PRs (30d)
16

Description

*Moving a couple ideas from an email thread here so we don't lose them*

Currently the material for properties & indexers is organised as follows:

§15.7 Properties -> §15.7.2 Static and instance properties
Specification of properties
§15.7.3 Accessors -> §15.7.6 Virtual, sealed, override, and abstract accessors
Specification of accessors, shared by both properties and indexers. 15.7.3, 15.7.4 & 15.7.6, added by PR 837, have Notes explaining they are shared as they are written in terms of properties (by happenstance 15.7.5 is written in terms of both)
§15.8 Events
Specification of events
§15.9 Indexers -> §15.9.2 Indexer and Property Differences
Specification of indexers. 15.9.2 was added in PR 837 to bring the differences together at the end of 15.9

This is a bit mixed up and a little bit of shuffling may help. Having shared material being in subclauses of 15.7 seems wrong to me, but even just swapping Events & Indexers around so similar material is adjacent would help. Here is one possible shuffle:

§15.7 Properties -> §15.7.2 Static and instance properties
Specification of properties
§15.8 (prev 15.9) Indexers -> §15.8.2 (prev 15.9.2) Indexer and Property Differences
Specification of indexers
§15.9 Accessors
§15.9.1 General
The content of what is currently Notes on 15.7.3, 15.7.4 & 15.7.6
§15.9.2 (prev 15.7.3) Accessors -> §15.9.5 (prev 15.7.6) Virtual, sealed, override, and abstract accessors
Specification of accessors, shared by both properties and indexers.
§15.10 Events
Specification of events

And related note:

We currently define most aspects of all member function kinds in the Classes chapter, and enhance/restrict a few of those in the Structs chapter, and then again to a lesser extent in the Interfaces chapter. Coming soon in V8, we’ll be looking at PR #681, which adds support for default member function member implementations in interfaces for pretty much *all* member function kinds. As you will see from some of the proposed edits in that PR, I tried to deal with having the core definition of each given function member kind in the Classes chapter, and then amending/extending it in the others.

Taking this idea into account, does it make sense to put all the core member function details in a “Member functions” chapter, and have the Classes, Structs, Interfaces chapters point there, with each containing only supplemental information?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.