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

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




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

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

Tim Mackinnon wrote
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

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

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.

+100

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

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".
___
montyos.wordpress.com

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

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

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 11/07/2018 21:21, Sean P. DeNigris wrote:
+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