Re: [Pharo-users] Naming parameters - conventions?
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 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 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 > >
Re: [Pharo-users] Naming parameters - conventions?
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
Re: [Pharo-users] Naming parameters - conventions?
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 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 >
Re: [Pharo-users] Naming parameters - conventions?
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
Re: [Pharo-users] Naming parameters - conventions?
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"
> To: "Pharo Users Newsgroup"
> 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
Re: [Pharo-users] Naming parameters - conventions?
+100
//
Encrypted email at jgpfers...@protonmail.com
Web: www.objectnets.net and www.objectnets.org
> On Jul 11, 2018, at 18:20, Richard Sargent
> 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
>
Re: [Pharo-users] Naming parameters - conventions?
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 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 :
>> 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
>>
>>
Re: [Pharo-users] Naming parameters - conventions?
>
> 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 :
> 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
>
>
>
Re: [Pharo-users] Naming parameters - conventions?
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
Re: [Pharo-users] Naming parameters - conventions?
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
Re: [Pharo-users] Naming parameters - conventions?
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
Re: [Pharo-users] Naming parameters - conventions?
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
