[swift-evolution] When to use argument labels, part DEUX

[Radosław Pietruszewski]

> To do a complete evaluation also need to think about
> what applying the guidelines will do to your own code.

You’re right! I extracted the list of method definitions from my app and looked through it.

The overwhelming majority of my methods either take no arguments, or start with a verb and make a phrase where the first parameter doesn’t require a label (rule B1).

Some methods I noticed (I don’t know if this is useful for you, but if it is then here you go):

	private func setHandoffState(hash hash: String, fallbackURL: String, title: String? = nil, searchable: Bool) {

This seems OK to me, but I’m not entirely sure if the guidelines suggest I _should_ put a preposition there, i.e.

	setHandoffStateFor(hash: a, fallbackURL: b, …)

I don’t think I should — I don’t see how “for” adds to clarity here, but I want to make sure if I interpret the proposed guidelines right.

	func actionForCommand(command: UIKeyCommand) -> String? {

This should become “actionFor(command: c)” — which isn’t an obvious win, but I certainly don’t mind it.

	private func createAttribute(tag: SecItemAttr, _ data: NSString?) -> SecKeychainAttribute? {

Forgive my barbaric removal of external labels. It should be `createAttribute(tag: t, data: d)`. Alternatively, it could be `attributeFor(tag: t, data: d)` — I could go either way.

(adding to my thoughts on the later proposal of moving preposition inside parens, the symmetry in param labels would likely be broken here, because it doesn’t seem necessary to add “for”/“with” when I go with “createAttribute”, but for the noun-only version it would have to be “attribute(forTag: t, data: d)”.)

	func attachmentForImage(image: UIImage) throws -> Attachment {
	func attachmentForData(data: NSData) -> Attachment {
	func attachmentForFileURL(url: NSURL) throws -> Attachment {

This should be `attachmentFor(image:)`, `attachmentFor(data:)`, and `attachmentFor(fileURL:)`. This seems like a win, since related methods for different data types are grouped more tightly together. (I could also — like you suggested about not optimizing for method families — make an enum, but it would be overkill since it’s not API for public consumption. I should mark those as private.)

	private func messageCell(label label: String) -> MessageCell {
	private func cellForTask(task: Task, enabled: Bool = true) -> TaskCell {

Hm, those are inconsistent. I could go with `cellFor(message:)` and `cellFor(task:)`, which would be consistent with the guidelines. OTOH, since they return different types, I liked that they had different names… `taskCellFor(task:)` is redundant. Perhaps `taskCellFor(_:)` and `messageCellFor(_:)`.

	func generate(fill: Double, text: String) -> CLKComplicationTemplate {

`templateFor(fill:, text:)`

	func update(from old: TaskCommentRowModel?, to new: TaskCommentRowModel) {

That’s the, IMO rare, circumstance where the preposition *does* make sense to go inside the parens.

* * *

I mentioned this in some other post before, but I also found a bunch of methods where the first parameter should be labeled, but isn’t, because without an easy shortcut like the old #param, I was just too lazy to do The Right Thing.

PS. If someone wanted to do the same thing and review methods in their project, here’s the quick&dirty Ruby script for this: https://gist.github.com/radex/b425c73afde84d88e4ca <https://gist.github.com/radex/b425c73afde84d88e4ca> 

HTH,
— Radek

> On 08 Feb 2016, at 21:55, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Mon Feb 08 2016, Radosław Pietruszewski <swift-evolution at swift.org> wrote:
> 
>> Dave,
>> 
>> First of all, thank you for enduring our nitpicks and complaints and
>> continuing to explore the subject :) I think we’re all better off for
>> it, and getting closer to the solution with each iteration.
>> 
>> You asked:
>> 
>>> 1. I'm not expecting these guidelines to make everybody optimally happy,
>>>  all the time, but they shouldn't be harmful.  Are there any cases for
>>>  which they produce results you couldn't live with?
>> 
>> And I think, by this standard, the guidelines you proposed seem to be
>> a success. Looking through Doug’s diffs, I see a lot of method names
>> that I don’t *love*, but I couldn’t find something I would hate.
> 
> That's great news!  Keep in mind, though, that Doug's results are just
> the result of trying to approximate application of the guidelines by
> using heuristics.  To do a complete evaluation also need to think about
> what applying the guidelines will do to your own code.
> 
> Thanks,
> 
> -- 
> -Dave
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160211/717ed2a5/attachment.html>