[swift-evolution] [Proposal] clarification around protocol implementation and protocol extensions

[David Waite]

> On Feb 18, 2017, at 12:40 AM, Xiaodi Wu <xiaodi.wu at gmail.com> wrote:
> 
> On Sat, Feb 18, 2017 at 1:07 AM, David Waite <david at alkaline-solutions.com <mailto:david at alkaline-solutions.com>> wrote:
> 
> I believe this proposal is different in that it only requires specification for clarity not for behavioral changes, and only requires the keyword to be specified for protocols known at the site of method/property declaration.
> 
> If indeed you frame your proposal in this way, a best effort to add clarity of intention, my feedback is that there are ways to gain the same (or at least, very similar) benefits without being source-breaking, and indeed without introducing new keywords at all.
> 
> For example:
> - Doc comments are parsed. We already have `- Parameter` in doc comments, which improved tooling could double-check to ensure that the stuff we put there matches the stuff in the function signature (hmm, that'd be a nice additive proposal, right?).
> - The same tool could be augmented to recognize a spelling such as `- RequiredBy:`, and you could list the specific protocols that require the method. Then, you would be warned at compiled time if your method is in fact not required by a protocol. This design has the side benefit of telling the reader of your code exactly what protocols require that method, not just that it's required by some protocol.

IMHO doc comment is no different than a keyword or attribute flagging the capability other than the color paint used on the bike shed. I’d disagree with an attribute or doc comment unless ‘override’ was also moved to be similar.

Documentation styles differ greatly between developers and projects, but I personally subscribe to the idea of self-documenting internal code, resorting to documentation when that is not possible. Published documentation (doc comments) are reserved for when code is meant to be accessed externally.

Even then, I wouldn’t document an *implementation* of a protocol unless the protocol was being implemented by a public type *and* left flexibility in the behavior of the implementation, Otherwise, I would rely on the documentation of the protocol.

For the vast majority of code, I simply don’t see people using doc comments by default. So this feature would have them creating doc comments for the purpose of indicating "RequiredBy"

Second, most of the reasons for marking a method or property as being required by a protocol go away if such a feature is optional per-method. Developers scanning code looking for the cause of odd behavior aren’t going to notice that there is a typo in the method signature, still, nor are they going to see a missing “RequiredBy” doc comment as a clue unless their coding style requires such (most likely enforced by a third party linter)

All that said, I’ve seen plenty of code attempt to indicate such a “RequiredBy” feature via extensions, e.g.

	extension ClassName : ProtocolName { … }

I could see a compromise of an opt-in feature where such an extension is expected to contain the body of the protocol implementation (or of multiple protocols, e.g. Equatable and Hashable), and that any non-private method in the extension would result in a warning if it was not applied toward implementing the specified protocols.

Is that something people would be interested in? I don’t know if it is just the weekend, but this thread has been very quiet.

> 
> The purpose isn’t to map methods to protocols, but to clarify that a method exists to meet the requirements of a protocol. Without this, a simple typo (or redefinition of methods such as with the changes in Swift 3’s importer) causes what you thought was conforming to a protocol to either fail, or worse silently change behavior.
> 
> As I demonstrate above, there are other designs possible that do not require source breakage, or even any new keywords, which recover essentially all of the benefits you list here. Such alternative designs would be opt-in, so those who care about this additional compiler help can use it, and those who do not won't need to, consistent with Swift's new emphasis on compatibility and its established emphasis on progressive disclosure.

The design I specified does not result in source breakage. There would be warnings for Swift 3 code compiled under Swift 4 saying that the keywords were missing, and that the behavior as if the keywords were specified is assumed.

Swift 4 code using the keywords would not be backward compatible with Swift 3, but I know of no similar backward compatibility requirements that Swift 4 code compile on Swift 3.

-DW


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170218/5eab435a/attachment.html>