How to name functions when you're writing about them

[hollance]

I just updated my Candy Crush tutorial to Swift and found that referencing function names from the text can be awkward.

For example, I have the method:

func convertPointFromColumn(column: Int, row: Int) -> CGPoint

This uses the style where the first argument is named as part of the function name.

So in the text, should I refer to this as:

• convertPointFromColumn()
• convertPointFromColumn(row:)
• convertPointFromColumn(column:, row:)

The first one is the shortest but also incomplete because row: is part of the function name.

The second one might be misleading because a reader may think row: is the argument, not part of the name.

The third one is the most correct, but also the longest and "noisiest".

Note that Xcode calls this method convertPointFromColumn(_, row:). That's also an option but not a very nice one...

[ColinEberhardt]

That's a very good question. Personally I always go for the first option:

convertPointFromColumn()

I know that technically it is not complete, and in cases may be ambiguous, but for writing I think it is sufficient.

On a related note, we need to add a section to the style guide about method naming, which should follow the same principle as Objective-C

From the Swift Language Guide:

Methods in Swift are very similar to their counterparts in Objective-C. As in Objective-C, the name of a method in Swift typically refers to the method’s first parameter using a preposition such as with, for, or by,

I think the example of convertPointFromColumn(row:) is most correct. The only way that would be ambiguous is if you named two methods like this:

convertPointFromColumn(#row:)
convertPointFromColumn(column:,row:)

If you did that, good chance you'd get slapped by an editor.

While writing my code, I've find myself switching between declaring functions like this:

convertPointFrom(#column:)

and this:

convertPointFromColumn(col:)

I was just trying them each out for a while until I could decide which I like more, but I'm still not sure. On one hand, I don't like always requiring the first parameter name, but on the other, it would make discussing them in text that much obvious. Thoughts?

--------- Original Message --------- Subject: Re: [swift-style-guide] How to name functions when you're writing about them (#32)
From: "ColinEberhardt" notifications@github.com
Date: 6/20/14 7:37 am
To: "raywenderlich/swift-style-guide" swift-style-guide@noreply.github.com

That's a very good question. Personally I always go for the first option:
convertPointFromColumn() I know that technically it is not complete, and in cases may be ambiguous, but for writing I think it is sufficient.
On a related note, we need to add a section to the style guide about method naming, which should follow the same principle as Objective-C
From the Swift Language Guide:
Methods in Swift are very similar to their counterparts in Objective-C. As in Objective-C, the name of a method in Swift typically refers to the method's first parameter using a preposition such as with, for, or by,

Reply to this email directly or view it on GitHub.

[macandyp]

+1 for convertPointFromColumn(row:).

Referring to the method tableView() would be rather confusing, versus tableView(cellForRowAtIndexPath:). And tableView(tableView:, cellForRowAtIndexPath:) is a bit redundant.

[rwenderlich]

I also like convertPointFromColumn(row:). It's unambiguous and similar to the way we named methods in the Objective-C style guide.

[gregheo]

I agree, that's the way to name this kind of function.

But: I don't like putting the first parameter in as part of the name in Swift.

My objection here is that you call the function like convertPointFromColumn(10, 20) and there's no mention of any row. And referring to it as convertPointFromColumn(row:) makes it seem like you would call it with a named parameter like convertPointFromColumn(10, row:20) which is also incorrect.

My suggestion:

func convertPointAt(#column: Int, #row: Int) -> CGPoint
convertPointAt(column: 10, row: 20)

And then when you want to talk about it, you say convertPointAt(column:, row:) or even the more compact convertPointAt(column:row:).

[gregheo]

I should clarify: column and row are like "siblings" here so it seems strange to make the column more prominent and put it right in the name convertPointFromColumn. Yes, I know that's how it was in Objective-C but this is the new Swift world.

For something like tableView(cellForRowAtIndexPath:) or prepareForSegue(sender:) the table view is not at the same "level" as the index path so I can understand why it's in the function name. Even there though, I don't like how tableView(cellForRowAtIndexPath:) actually takes two arguments but there's only one colon so it looks like it might just take one.

[cwagdev]

tableView(cellForRowAtIndexPath:) 

That definitely seems ambiguous. 
—
Sent from Mailbox

On Thu, Jun 26, 2014 at 10:52 PM, Greg Heo notifications@github.com
wrote:

I should clarify: column and row are like "siblings" here so it seems strange to make the column more prominent and put it right in the name. Yes, I know that's how it was in Objective-C but this is the new Swift world.

For something like tableView(cellForRowAtIndexPath:) or prepareForSegue(sender:) the table view is not at the same "level" as the index path so I can understand why it's in the function name. Even there though, I don't like how tableView(cellForRowAtIndexPath:) actually takes two arguments but there's only one colon so it looks like it might just take one.

Reply to this email directly or view it on GitHub:
#32 (comment)

Actually, you would call it with a named parameter.

convertPointFromColumn(col: Int, row: Int)

would be called as

convertPointFromColumn( 10, row: 20)

In Swift, the parameters after the first default to being required. In fact, if you were to try to declare the method like you did, with a #row, the compiler will actually give you a warning complaining about the extra #.

However, I agree, while writing I have been leaning more and more toward

convertPointFrom(#col: Int, row: Int)

--------- Original Message --------- Subject: Re: [swift-style-guide] How to name functions when you're writing about them (#32)
From: "Greg Heo" notifications@github.com
Date: 6/27/14 1:43 am
To: "raywenderlich/swift-style-guide" swift-style-guide@noreply.github.com
Cc: "elephantronic" chris@elephantronic.com

I agree, that's the way to name this kind of function.
But: I don't like putting the first parameter in as part of the name in Swift.
My objection here is that you call the function like convertPointFromColumn(10, 20) and there's no mention of any row. And referring to it as convertPointFromColumn(row:) makes it seem like you would call it with a named parameter like convertPointFromColumn(10, row:20) which is also incorrect.
My suggestion:
func convertPointAt(#column: Int, #row: Int) -> CGPoint convertPointAt(column: 10, row: 20) And then when you want to talk about it, you say convertPointAt(column:, row:) or even the more compact convertPointAt(column:row:).

Reply to this email directly or view it on GitHub.

[gregheo]

I should have clarified. The behaviour is different for instance methods and plain old functions out in module scope. Here's what I get in a playground:

func convertPointAt(column: Int, row: Int) -> CGPoint { return CGPoint(x: column, y: row) }
class Wrap {
  func convertPointAt(column: Int, row: Int) -> CGPoint { return CGPoint(x: column, y: row) }
}

var wrap = Wrap()
wrap.convertPointAt(20, row: 30)
convertPointAt(20, 30)

[gregheo]

Here's what I put in the style guide, notwithstanding my own confusion on how named parameters for functions vs methods work:

When referring to functions in prose (tutorials, books, comments) include the required parameter names from the caller's perspective.

Methods still look a little strange to me since they look like the first parameter is missing but adding the _ might look even stranger.

[edekhayser]

(Brought up by Tammy)
We never established a way to deal with methods with 3+ parameters. Should it be
method(first: second: third:)
or
method(first:, second:, third:)
or only include the first parameter, or something else?
Either way, there needs to be something specific to keep these situations consistent.

[ColinEberhardt]

How about opting for the naming that Xcode uses? Using the earlier example:

class MyClass {
  func convertPointFromColumn(column:, row:) {
  }
}

You would refer to the method as convertPointFromColumn(_:row:).

But if it was defined as a global function:

func convertPointFromColumn(column:, row:) {
}

It would be referred to as convertPointFromColumn(_:_:).

This naming exactly matches Xcode, and also as a bonus encourages people to learn about the purpose of underscore!