July 2018 - Pharo-users - lists.pharo.org

Re: [Pharo-users] Naming parameters - conventions?

by monty

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(a)testit.works> > To: "Pharo Users Newsgroup" <pharo-users(a)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

July 12, 2018

Re: [Pharo-users] Naming parameters - conventions?

by john pfersich

+100 /ââââââââââââââââââââ/ Encrypted email at jgpfersich(a)protonmail.com Web: www.objectnets.net and www.objectnets.org > On Jul 11, 2018, at 18:20, Richard Sargent <richard.sargent(a)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 >

July 12, 2018

Re: [Pharo-users] Naming parameters - conventions?

by 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 <chaetal(a)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(a)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 >> >>

July 12, 2018

Re: [Pharo-users] Naming parameters - conventions?

by 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 <kksubbu.ml(a)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 > > >

July 12, 2018

Re: [Pharo-users] Naming parameters - conventions?

by 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

July 12, 2018

Re: [Pharo-users] Email Google API for pharo

by oswall arguedas

Thank you very much for your answers. I will work on it. I give them feedback. Thanks Oswall ________________________________ De: Pharo-users <pharo-users-bounces(a)lists.pharo.org> en nombre de Sean P. DeNigris <sean(a)clipperadams.com> Enviado: miÃ©rcoles, 11 de julio de 2018 15:39:53 Para: pharo-users(a)lists.pharo.org Asunto: Re: [Pharo-users] Email Google API for pharo Peter UhnÃ¡k wrote > I've used it last year or so and it was very nice to use. Anything public we can use for inspiration? ----- Cheers, Sean -- Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html

July 12, 2018

Re: [Pharo-users] XML support for pharo

by oswall arguedas

Thanks Franz and Monty. I'm working on it, everything is going very well. The feedback when I master it. Oswall ________________________________ De: Pharo-users <pharo-users-bounces(a)lists.pharo.org> en nombre de monty <monty2(a)programmer.net> Enviado: miÃ©rcoles, 11 de julio de 2018 03:32 Para: pharo-users(a)lists.pharo.org Asunto: Re: [Pharo-users] XML support for pharo This is the latest version of the XML/XPath Scraping Booklet: <https://files.pharo.org/books-pdfs/booklet-Scraping/2018-01-07-scrapingbook…> Scraping HTML with XPath - files.pharo.org<https://files.pharo.org/books-pdfs/booklet-Scraping/2018-01-07-scrapingbook…> files.pharo.org 1.6 Alargeexample â¢ Siblings.Siblingsarechildnodesthathavethesameparent.Thecard-name,types,year,rarity,expansionandcardtextelementsareallsib- ___ montyos.wordpress.com

July 12, 2018

Re: [Pharo-users] XML support for pharo

by oswall arguedas

Thanks Franz and Monty. I'm working on it, everything is going very well. The feedback when I master it. Oswall ________________________________ De: Pharo-users <pharo-users-bounces(a)lists.pharo.org> en nombre de monty <monty2(a)programmer.net> Enviado: miÃ©rcoles, 11 de julio de 2018 03:32:35 Para: pharo-users(a)lists.pharo.org Asunto: Re: [Pharo-users] XML support for pharo This is the latest version of the XML/XPath Scraping Booklet: <https://files.pharo.org/books-pdfs/booklet-Scraping/2018-01-07-scrapingbook…> ___ montyos.wordpress.com

July 12, 2018

Re: [Pharo-users] Naming parameters - conventions?

by Richard Sargent

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

July 12, 2018

Re: [Pharo-users] Thoughts on mini Smalltalk exercises

by Ben Coman

On 11 July 2018 at 22:43, Tim Mackinnon <tim(a)testit.works> wrote: > Hi - Iâm trying to help Sam kickstart Pharo working Ian the exercism platform. For those less familiar, exercism is a platform with a series of exercises that users/students âcheckoutâ and then run a test to guide them through completing the code to then progress to the next challenge. There is also the ability to comment on each otherâs progress and see examples of otherâs solutions. Most languages are more traditional file based examples, so it would be nice to have Smalltalk as something a bit different. Although we think Tonel 2 will be an excellent vehicle for participating alongside other languages as it helps us fit in a little easier (nice how all our initiatives are coming together to make this easy). > > As you can imagine, exercises start out very simple and then increase in complexity. My question however, is about the early exercise like HelloWorld, LeapYear etc. > > These tend to be single method problems of just a few lines, requiring no instance variables (this all comes later). > > Iâm wondering about peopleâs thoughts on whether we should introduce early Smalltalk examples as just class methods and later introduce instance methods and âclass constructor methods â? Or is this more confusing for students? Essentially we are battling with the familiarity of the C âmainâ method - and looking at python and ruby solutions, they initially start with no objects and just main style methods. > > E.g. hello world can be simply: HelloWorld sayHello. vs HelloWorld new sayHello. > > I can see proâs/conâs either way - but wondering what others think. I've installed Sam's PR and my main thought is that the System Browser defaults to the instance side, so its easier for fresh students to misplace code when it ends up on the class side, when they close a browser and open a new one. The unit test the students run takes care the of needing to send #new to get an object, so I think its simpler to keep implementations on the instance-side. One downside is that the Quality Assistant indicates that utility methods (having no reference to instance variables) should belong on the class side. It might be good that this warning is disabled globally when the Exercism tool is installed. I think using a Manifest to do this would look complicated to newcomers. Later on some specific Factory Pattern exercises might be useful to introduce students to using class-side methods. cheers -ben

July 12, 2018