Naming parameters - conventions?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Naming parameters - conventions?

Tim Mackinnon
Hi everyone, something I’ve meant to ask over the years, as I’ve seen lots of variation and was taught something else in the day...

What is the suggested way of naming parameters?

I was taught {“a”/“an”}DataType, so it would be:

#name: aString

Which works ok (although falls apart if you refactor as the tools don’t interpret it - although I guess could be improved to do so)

However often I find myself wanting to communicate a bit better as in:

#name: fullNameString

Which isn’t strictly a datatype (and I tend to leave out the a/an when I do this). But it feels a bit off piste and it does make me consider whether my selector is named badly and should be:

#fullName: aString

Which takes me back to the convention I learned long ago.

This said however, we often need to match similar #on:do, #in: generic selector names and then it’s not always obvious the intent of parameter.

Any thoughts to share?

I ask because for exercism, we should try and set a good example.

Tim

Sent from my iPhone

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Paul DeBruicker
I generally go for intention revealing (e.g. fullName) because the class of
the parameter can change arbitrarily. e.g. your aString might become a Name
object that can answer something useful when you know just the first or
family name.  But I also mostly write code for my own consumption.  


If there is anything recommended/specified in


https://www.amazon.com/Smalltalk-Best-Practice-Patterns-Kent/dp/013476904X

I'd use it in training materials.  


I'm away from the house but can look in my copy later if no one else chimes
in with a better answer.  


It also seems like a "how much milk do you like in your coffee?" choice
where the tradeoffs between one vs the other isn't high and the code in
action will let you know whether you've got it right.  






Tim Mackinnon wrote

> Hi everyone, something I’ve meant to ask over the years, as I’ve seen lots
> of variation and was taught something else in the day...
>
> What is the suggested way of naming parameters?
>
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString
>
> Which works ok (although falls apart if you refactor as the tools don’t
> interpret it - although I guess could be improved to do so)
>
> However often I find myself wanting to communicate a bit better as in:
>
> #name: fullNameString
>
> Which isn’t strictly a datatype (and I tend to leave out the a/an when I
> do this). But it feels a bit off piste and it does make me consider
> whether my selector is named badly and should be:
>
> #fullName: aString
>
> Which takes me back to the convention I learned long ago.
>
> This said however, we often need to match similar #on:do, #in: generic
> selector names and then it’s not always obvious the intent of parameter.
>
> Any thoughts to share?
>
> I ask because for exercism, we should try and set a good example.
>
> Tim
>
> Sent from my iPhone





--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Sean P. DeNigris
Administrator
Paul DeBruicker wrote
> It also seems like a "how much milk do you like in your coffee?" choice
> where the tradeoffs between one vs the other isn't high and the code in
> action will let you know whether you've got it right.  

+1. I also use both. My heuristic is for shorter methods, and methods with
one argument, I tend to lean toward fullNameString and when I need to
differentiate multiple arguments or reference the arg way down in a method
(probably a good sign to refactor) I lean the other way. But I think Paul
said it best that it's probably more a personal style/aesthetic choice than
anything worth spending a lot of energy on.



-----
Cheers,
Sean
--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Richard Sargent
Administrator
In reply to this post by Tim Mackinnon
Tim Mackinnon wrote

> Hi everyone, something I’ve meant to ask over the years, as I’ve seen lots
> of variation and was taught something else in the day...
>
> What is the suggested way of naming parameters?
>
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString
>
> Which works ok (although falls apart if you refactor as the tools don’t
> interpret it - although I guess could be improved to do so)
>
> However often I find myself wanting to communicate a bit better as in:
>
> #name: fullNameString
>
> Which isn’t strictly a datatype (and I tend to leave out the a/an when I
> do this). But it feels a bit off piste and it does make me consider
> whether my selector is named badly and should be:
>
> #fullName: aString
>
> Which takes me back to the convention I learned long ago.
>
> This said however, we often need to match similar #on:do, #in: generic
> selector names and then it’s not always obvious the intent of parameter.
>
> Any thoughts to share?

In my opinion, worth what you pay for it, the goal is to communicate and set
the reader's expectations. You want the reader to know what kind of
behaviours the argument should provide.

So, when creating a setter method, it is sufficient to name the argument
"aString". The method selector is telling you the purpose of the string. The
argument is telling you that it is no more and no less than a string. It
isn't trying to convey that there is a structure to that string. Just that
the name is a string.

Likewise, when naming a parameter for a more complex method you may need to
say more, depending on what the selector itself says.
e.g. #blahBlahBlahWithName: can easily work with "aString".

Conversely, a method that takes multiple string arguments needs to
effectively distinguish them from each other.
e.g. #blahBlahBlahWithName:address:telephone: needs to do better than Dr.
Seuss (aString1, aString2, etc.) In this example, I tend to use e.g.
"nameString", "addressString", and "telephoneString". This conveys the
purpose of each argument and identifies the behaviours one should expect.

I am *not* a fan of argument names like "aNameString", since that can
mislead readers into expecting name-specific behaviours from the argument.



> I ask because for exercism, we should try and set a good example.
>
> Tim
>
> Sent from my iPhone





--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

K K Subbu
In reply to this post by Tim Mackinnon
On Thursday 12 July 2018 03:54 AM, Tim Mackinnon wrote:
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString

It depends on the current level of abstraction. At the lowest levels, it
is okay to use basic types like aString since classes (types) define
behavior. If you are operating at a much higher level, say transfering
money between two accounts, you would do:

#transferMoney from: aPayer to: aPayee

where both aPayer and aPayee could be anAccountHolder

Essentially, the idea to keep the message part as close to normal
statements as possible.

The book "A Mentoring Course Smalltalk" by Andres Valloud covers this
aspect in great detail.

Regards .. Subbu


Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Dennis Schetinin
It depends on the current level of abstraction. If you are operating at a much higher level, say transfering 
money between two accounts, you would do:
 
#transferMoney from: aPayer to: aPayee

where both aPayer and aPayee could be anAccountHolder

Why not 

#transferMoney from: payerAccountHolder to: payeeAccountHolder

?

And how does the naming depend on level of abstraction?

Practically, when a (potential) user of the method is going to invoke it, one of the first questions will be 'what kind of object I can/should pass there?'. With the classic Smalltalk convention it is quite obvious (though, the convention is not perfect itself and sometimes/often is not enough). With the  aPayer and aPayee the user will have to read the method code to learn that. 


--

Best regards,


Dennis Schetinin



чт, 12 июл. 2018 г. в 6:29, K K Subbu <[hidden email]>:
On Thursday 12 July 2018 03:54 AM, Tim Mackinnon wrote:
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString

It depends on the current level of abstraction. At the lowest levels, it
is okay to use basic types like aString since classes (types) define
behavior. If you are operating at a much higher level, say transfering
money between two accounts, you would do:

#transferMoney from: aPayer to: aPayee

where both aPayer and aPayee could be anAccountHolder

Essentially, the idea to keep the message part as close to normal
statements as possible.

The book "A Mentoring Course Smalltalk" by Andres Valloud covers this
aspect in great detail.

Regards .. Subbu


Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Tim Mackinnon
This payer/payee example is exactly what I was thinking about, and I’ve tended to do as Dennis suggests and use a type suffix on the name - and wondered if that was what most people do.

I’ll certainly check what Andreas says on the topic.

Tim 

Sent from my iPhone

On 12 Jul 2018, at 06:31, Dennis Schetinin <[hidden email]> wrote:

It depends on the current level of abstraction. If you are operating at a much higher level, say transfering 
money between two accounts, you would do:
 
#transferMoney from: aPayer to: aPayee

where both aPayer and aPayee could be anAccountHolder

Why not 

#transferMoney from: payerAccountHolder to: payeeAccountHolder

?

And how does the naming depend on level of abstraction?

Practically, when a (potential) user of the method is going to invoke it, one of the first questions will be 'what kind of object I can/should pass there?'. With the classic Smalltalk convention it is quite obvious (though, the convention is not perfect itself and sometimes/often is not enough). With the  aPayer and aPayee the user will have to read the method code to learn that. 


--

Best regards,


Dennis Schetinin



чт, 12 июл. 2018 г. в 6:29, K K Subbu <[hidden email]>:
On Thursday 12 July 2018 03:54 AM, Tim Mackinnon wrote:
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString

It depends on the current level of abstraction. At the lowest levels, it
is okay to use basic types like aString since classes (types) define
behavior. If you are operating at a much higher level, say transfering
money between two accounts, you would do:

#transferMoney from: aPayer to: aPayee

where both aPayer and aPayee could be anAccountHolder

Essentially, the idea to keep the message part as close to normal
statements as possible.

The book "A Mentoring Course Smalltalk" by Andres Valloud covers this
aspect in great detail.

Regards .. Subbu


Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

John Pfersich
In reply to this post by Richard Sargent
+100

/————————————————————/

On Jul 11, 2018, at 18:20, Richard Sargent <[hidden email]> wrote:

Tim Mackinnon wrote
Hi everyone, something I’ve meant to ask over the years, as I’ve seen lots
of variation and was taught something else in the day...

What is the suggested way of naming parameters?

I was taught {“a”/“an”}DataType, so it would be:

#name: aString

Which works ok (although falls apart if you refactor as the tools don’t
interpret it - although I guess could be improved to do so)

However often I find myself wanting to communicate a bit better as in:

#name: fullNameString

Which isn’t strictly a datatype (and I tend to leave out the a/an when I
do this). But it feels a bit off piste and it does make me consider
whether my selector is named badly and should be:

#fullName: aString

Which takes me back to the convention I learned long ago.

This said however, we often need to match similar #on:do, #in: generic
selector names and then it’s not always obvious the intent of parameter.

Any thoughts to share?

In my opinion, worth what you pay for it, the goal is to communicate and set
the reader's expectations. You want the reader to know what kind of
behaviours the argument should provide.

So, when creating a setter method, it is sufficient to name the argument
"aString". The method selector is telling you the purpose of the string. The
argument is telling you that it is no more and no less than a string. It
isn't trying to convey that there is a structure to that string. Just that
the name is a string.

Likewise, when naming a parameter for a more complex method you may need to
say more, depending on what the selector itself says.
e.g. #blahBlahBlahWithName: can easily work with "aString".

Conversely, a method that takes multiple string arguments needs to
effectively distinguish them from each other.
e.g. #blahBlahBlahWithName:address:telephone: needs to do better than Dr.
Seuss (aString1, aString2, etc.) In this example, I tend to use e.g.
"nameString", "addressString", and "telephoneString". This conveys the
purpose of each argument and identifies the behaviours one should expect.

I am *not* a fan of argument names like "aNameString", since that can
mislead readers into expecting name-specific behaviours from the argument.



I ask because for exercism, we should try and set a good example.

Tim

Sent from my iPhone





--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

monty-3
In reply to this post by Tim Mackinnon
The primary trade-off is between Type Suggesting vs. Role Suggesting parameter names.

For example, aString and aSymbol tell us only what type of object the parameter expects, while aName and aTitle tell us the *role* (or purpose) of the parameter, with the expected type hopefully obvious.

You can combine the two, like aNameString, or aTitleSymbol, and this should be done where necessary to prevent confusion. For example, in XMLParser I have a URI class, XMLURI, and to avoid confusion over parameters that accept both XMLURIs and URI strings, I use anXMLURIOrURIString.

Using "a" and "an" prefixes is always a good idea, because it prevents collisions with instance variables, allows you to tell at a glance that an identifier is a parameter and not an inst var, and it produces more natural, readable message signatures, like "copyFrom: anOldPath to: aNewPath".

> Sent: Wednesday, July 11, 2018 at 6:24 PM
> From: "Tim Mackinnon" <[hidden email]>
> To: "Pharo Users Newsgroup" <[hidden email]>
> Subject: [Pharo-users] Naming parameters - conventions?
>
> Hi everyone, something I’ve meant to ask over the years, as I’ve seen lots of variation and was taught something else in the day...
>
> What is the suggested way of naming parameters?
>
> I was taught {“a”/“an”}DataType, so it would be:
>
> #name: aString
>
> Which works ok (although falls apart if you refactor as the tools don’t interpret it - although I guess could be improved to do so)
>
> However often I find myself wanting to communicate a bit better as in:
>
> #name: fullNameString
>
> Which isn’t strictly a datatype (and I tend to leave out the a/an when I do this). But it feels a bit off piste and it does make me consider whether my selector is named badly and should be:
>
> #fullName: aString
>
> Which takes me back to the convention I learned long ago.
>
> This said however, we often need to match similar #on:do, #in: generic selector names and then it’s not always obvious the intent of parameter.
>
> Any thoughts to share?
>
> I ask because for exercism, we should try and set a good example.
>
> Tim
>
> Sent from my iPhone
>
>
___
montyos.wordpress.com

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Erik Stel
In reply to this post by Tim Mackinnon
In the day, I learned from Smalltalk with Style:
http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf

On PDF-page 13 naming starts. On PDF-page 29 parameter names are explained
(but refers back to typed names for example). Naming ends at PDF-page 35. So
quite elaborate explanation of naming ;-).

In practice I also mix typed names (aCollection), semantic names (addresses)
and a combination (anAddressCollection). I prefer the combination except for
trivial situations or when the (class and) method name provide(s) enough
context (name: aString). This later might in itself be less trivial if the
context get broader than class and method (name).

@Tim, the book might be useful for more than just naming since it covers
quite some ground.




--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Tim Mackinnon
Sounds like what I’ve been doing is what others do too - I just wasn’t sure if my memory had served me well. It was great to be reminded about some of the subtleties though - hadn’t thought about a/an stopping inst var collisions.

I actually have an original copy of that style book, I was working at OTI at the time and knew Suzanne and Dave and we were all given a copy (probably worth a quick skim again)

Thanks everyone

Tim

Sent from my iPhone

> On 12 Jul 2018, at 11:09, Erik Stel <[hidden email]> wrote:
>
> In the day, I learned from Smalltalk with Style:
> http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf
>
> On PDF-page 13 naming starts. On PDF-page 29 parameter names are explained
> (but refers back to typed names for example). Naming ends at PDF-page 35. So
> quite elaborate explanation of naming ;-).
>
> In practice I also mix typed names (aCollection), semantic names (addresses)
> and a combination (anAddressCollection). I prefer the combination except for
> trivial situations or when the (class and) method name provide(s) enough
> context (name: aString). This later might in itself be less trivial if the
> context get broader than class and method (name).
>
> @Tim, the book might be useful for more than just naming since it covers
> quite some ground.
>
>
>
>
> --
> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
>


Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Tim Mackinnon
Having refreshed my memory by rereading that section of the style book - I see the source of my discomfort... I don’t find the guidelines on parameters very strong - and I think (like others) I side more with guideline 25 most of the time where it’s sensible (not just for multiple similar parameters).

Thus my preference seems to be for semantic typed naming eg:

fullNameString, sourceCollection, ageNumber (this one feels weird though), indexingInteger

I’m still a little unsure by using a/an as a prefix when doing semantic typed naming  - I think the style book is suggesting that prefix is for typed names (exclusively?).

I think the risk of collision with inst var names is low (and guideline 9 and it’s introduction seem to favour semantic naming for inst vars anyway) but I do recall once seeing someone use a prefix “my” on all inst vars. That was kind of cute, and seemed to read ok - and sort of encouraged you to add the setter/getter (without my) when needed. But maybe safer to avoid that convention I’m guessing?

Tim

Sent from my iPhone

> On 12 Jul 2018, at 12:27, Tim Mackinnon <[hidden email]> wrote:
>
> Sounds like what I’ve been doing is what others do too - I just wasn’t sure if my memory had served me well. It was great to be reminded about some of the subtleties though - hadn’t thought about a/an stopping inst var collisions.
>
> I actually have an original copy of that style book, I was working at OTI at the time and knew Suzanne and Dave and we were all given a copy (probably worth a quick skim again)
>
> Thanks everyone
>
> Tim
>
> Sent from my iPhone
>
>> On 12 Jul 2018, at 11:09, Erik Stel <[hidden email]> wrote:
>>
>> In the day, I learned from Smalltalk with Style:
>> http://sdmeta.gforge.inria.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf
>>
>> On PDF-page 13 naming starts. On PDF-page 29 parameter names are explained
>> (but refers back to typed names for example). Naming ends at PDF-page 35. So
>> quite elaborate explanation of naming ;-).
>>
>> In practice I also mix typed names (aCollection), semantic names (addresses)
>> and a combination (anAddressCollection). I prefer the combination except for
>> trivial situations or when the (class and) method name provide(s) enough
>> context (name: aString). This later might in itself be less trivial if the
>> context get broader than class and method (name).
>>
>> @Tim, the book might be useful for more than just naming since it covers
>> quite some ground.
>>
>>
>>
>>
>> --
>> Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Naming parameters - conventions?

Esteban A. Maringolo
In reply to this post by Sean P. DeNigris


On 11/07/2018 21:21, Sean P. DeNigris wrote:

> Paul DeBruicker wrote
>> It also seems like a "how much milk do you like in your coffee?" choice
>> where the tradeoffs between one vs the other isn't high and the code in
>> action will let you know whether you've got it right.  
>
> +1. I also use both. My heuristic is for shorter methods, and methods with
> one argument, I tend to lean toward fullNameString and when I need to
> differentiate multiple arguments or reference the arg way down in a method
> (probably a good sign to refactor) I lean the other way. But I think Paul
> said it best that it's probably more a personal style/aesthetic choice than
> anything worth spending a lot of energy on.

+1 to both.

Although a in method like: #setFirstName:lastName: I usually use
firstNameString and lastNameString respectively, mostly to not clash
with instance variables firstName and lastName.

Another criteria is to never name a parameter as aSomething if Something
isn't a class (and of course the class of the passed argument). The same
applies to #asSomething.

And _never_ use anObject as name, unless it really can hold any class of
object.


--
Esteban A. Maringolo