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
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
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
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
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
+100 /ââââââââââââââââââââ/ Encrypted email at jgpfersich@protonmail.com Web: www.objectnets.net and www.objectnets.org
On Jul 11, 2018, at 18:20, Richard Sargent <richard.sargent@gemtalksystems.com> 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
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
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 <kksubbu.ml@gmail.com>:
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. Iâll certainly check what Andreas says on the topic. Tim Sent from my iPhone On 12 Jul 2018, at 06:31, Dennis Schetinin <chaetal@gmail.com> 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 <kksubbu.ml@gmail.com>:
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
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" <tim@testit.works> To: "Pharo Users Newsgroup" <pharo-users@lists.pharo.org> 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
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
On 12 Jul 2018, at 11:09, Erik Stel <erik.stel@gmail.com> 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
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 <tim@testit.works> 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 <erik.stel@gmail.com> 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
participants (10)
-
Dennis Schetinin -
Erik Stel -
Esteban A. Maringolo -
john pfersich -
K K Subbu -
monty -
Paul DeBruicker -
Richard Sargent -
Sean P. DeNigris -
Tim Mackinnon