[swift-evolution] Make non-void functions @warn_unused_result by default

[Erica Sadun]

> On Mar 2, 2016, at 10:45 AM, Chris Lattner via swift-evolution <swift-evolution at swift.org> wrote:
> 
> You’re right, I agree there are also caveats. That said, they seem so completely minor (compared to the win of changing the behavior) that the answer seems clear here.  That said, it is all moot unless someone comes up with a formal proposal for us to discuss rigorously :-)
> 
> -Chris

First draft, in quite rough form: https://gist.github.com/erica/c8ddb9c7a1154a98a703
Supporting survey:  Survey Link <https://www.surveymonkey.com/r/6F9XZY6>

Have at it. 

-- Erica

Make non-Void functions default to @warn_unused_result

Proposal: SE-00XX
Author(s): Erica Sadun <http://github.com/erica>
Status: TBD
Review manager: TBD
 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#introduction>Introduction

In Swift's current incarnation, annotating methods and functions with @warn_unused_result informs the compiler that a non-void return type should be consumed. It is an affirmative declaration. In its absence, ignored results do not raise warnings or errors.

In its present form, this declaration attribute helps differentiate between mutating and non-muting pairs. It optionally offers a mutating-in-place alternative when an expected return value is not consumed. In the following example, the compiler suggests using sortInPlace for unused results.

@warn_unused_result(mutable_variant="sortInPlace")
public func sort() -> [Self.Generator.Element]
I propose to flip this default behavior. It's far more likely for an unused result to indicate programmer error than confusion between mutating and non-mutating function pairs. This proposal recommends reversing the default and making "warn on unused result" the default behavior for Swift.

This proposal was discussed on-list in a variety of threads, most recently Make non-void functions warn_unused_result by default <http://article.gmane.org/gmane.comp.lang.swift.evolution/8417>.

 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#motivation>Motivation

In current Swift, the following code compiles and run without warning:

import Darwin

sin(M_PI_4)
Outside of a playground, where evaluation results are of interest in and of themselves, it's unlikely any programmer would write this code intending to execute a Sine function and then discard the result.

Under this proposal, the Swift compiler warns about unused results except in cases where developers have specifically permitted this behavior. 

Real world examples of discardable results include NSUserDefaults' synchronize function (returns Bool) and printf(returns an int). The proposed change forces developers to intentionally discard results by annotating their declarations. This should significantly reduce real-world bugs due to the accidental omission of code that consumes results.

This proposal does not ignore the positive utility of pairing in-place procedural and value-returning functional implementations and retains the ability to enable the compiler and the Quick Help system to cross reference between the two.

 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#detail-design>Detail Design

Under this proposal, the compiler will emit a warning when any method or function that returns a non-void value is called without using its result. To suppress this warning, the developer must affirmatively mark the function to allow the result to be ignored.

Note: Ongoing advisory survey about detail design <http://ericasadun.com/2016/03/02/survey-help-redesign-swifts-unused-result-system/>.

In the final version of this proposal, this approach will take one of the following forms:

@attribute func f() -> T {}
func f() @attribute -> T {}
func f() -> @attribute T {} (I prefer this one) @ func f() -> T | Void {}
 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#mutable-variants>Mutable Variants

The Swift master change log <https://github.com/apple/swift/blob/master/CHANGELOG.md> notes the introduction of doc comment fields that engage with the code completion engine to deliver better results:

Three new document comment fields, namely - keyword:, - recommended: and - recommendedover:, allow Swift users to cooperate with code completion engine to deliver more effective code completion results. The - keyword: field specifies concepts that are not fully manifested in declaration names. - recommended: indicates other declarations are preferred to the one decorated; to the contrary, - recommendedover: indicates the decorated declaration is preferred to those declarations whose names are specified.
This proposal recommends introducing two further comment fields, specifically mutableVariant and immutableVariantto take over the role of the former mutable_variant: argument and offer recommendations in both directions.

Under this scheme, whatever attribute name is chosen to modify function names or return types will not use arguments.

The message argument that formerly provided a textual warning when a function or method was called with an unused result will be discarded entirely and subsumed by document comments.

 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#prefix-attribute-names>Prefix attribute names

The recommended prefix attribute will be built around one of the following names:

Optional result
Suppress unused result warning
Discardable result
Allow unused result
No warn unused result
Ignorable result
Incidental result
Or another name that occurs during discussion.
 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#type-decoration-attribute-names>Type decoration attribute names

The recommended decoration attribute will be built around one of the following names:

discardable
incidental
elective
discretionary
voluntary
voidable
@_ (underscore)
Or another name that occurs during discussion
 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#alternatives-considered>Alternatives Considered

Once the primary contenders have been selected, the alternatives mentioned above will be moved to this section.

 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#snake-case>Snake Case

It should be noted that this proposal, if accepted, removes two of the last remaining instances of snake_case in the Swift language.

 <https://gist.github.com/erica/c8ddb9c7a1154a98a703#acknowledgements>Acknowledgements

Thanks Chris Lattner, Gwendal Roué, if you want your name added, please let me know
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160302/8ac23994/attachment.html>