[doc] Add an embryonic section on stdlib coding style #25810
Conversation
lorentey
requested review from
milseman,
Catfish-Man,
airspeedswift and
stephentyrone
| Initializers don't have a dedicated name we can put the underscore on; instead, we add the underscore on the first argument label: `init(_value: Int)`. If the initializer doesn't have any parameter, then we add a dummy parameter of type Void with an underscored label: for example, `UnsafeBufferPointer.init(_empty: ())`. | ||
|
|
||
| This rule ensures we don't accidentally clutter the public namespace with `@usableFromInline` things (which could prevent us from choosing the best names for new public API), and it also makes it easy to see at a glance if a piece of stdlib code uses any non-public entities. | ||
|
|
There was a problem hiding this comment.
Why? In general, or only if it's part of the ABI?
There was a problem hiding this comment.
When the underscoring rule was introduced, everything in the stdlib was effectively inlinable.
This is no longer the case, but I see no reason to cease applying the rule. I find the underscores are a useful signal when I read the code.
On a practical level, it would be all too easy to accidentally slap on @usableFromInlne on an non-underscored internal method without renaming it.
There was a problem hiding this comment.
Do members of internal types also need an underscore?
One the one hand, an internal type _Foo may become public at one point, but we want its ABI imprint to remain. We'd change _Foo to public and say public typealias Foo = _Foo. At that point, it has many violations of the underscore rule. On the other hand, I don't think this is the sort of scenario to design an entire convention around.
There was a problem hiding this comment.
Internal types need to have an underscore in the type name. The members need not have an underscore themselves (and often cannot, because of protocol conformances).
The proper way to make a previously @usableFromInline internal struct _Foo public would be to keep the existing type and to wrap it in a new public struct. (Unless the internal API happens to be accepted verbatim as public. But that is exceedingly unlikely.)
To make a previously internal/private (non-usableFromInline) type public, we remove the old type and replace it wholesale with the new public API, adjusting use-sites as necessary.
|
Why don't we just make https://github.com/apple/swift/blob/master/docs/AccessControlInStdlib.rst a section in this document? |
|
That document is somewhat out of date -- we can now use private/fileprivate in the stdlib. |
|
Sure, if we don't just remove it, we should update it as well. I prefer the manual being longer and fully incorporating this knowledge, but Github's markdown doesn't scale as well towards larger documents so that's a weak opinion. |
| @@ -44,6 +44,20 @@ TODO: Should this subsume or link to [AccessControlInStdlib.rst](https://github. | |||
| 1. Frequently Encountered Issues | |||
|
|
|||
|
|
|||
| ## Coding style | |||
|
|
|||
| - The stdlib currently has a hard line length limit of 80 characters. | |||
There was a problem hiding this comment.
Do we actually want to maintain/enshrine this?
There was a problem hiding this comment.
I hedge it with "currently". This is a contributor guide, so it should document the rules we have. The 80-char limit is definitely something people need to be aware of.
We talked about bumping the limit, and I think we agreed it would be desirable, but we have not decided how/when we do it. I don't think we should change this while we still have an active release branch.
|
@swift-ci please smoke test |
|
@swift-ci smoke test macOS platform |
|
@swift-ci smoke test and merge |
Add an extremely unfinished section on the stdlib coding style, specifically on naming internal things.