Re: [Pharo-dev] [Pharo-users] New book: Pharo with Style
--- Begin Message --- Hi Richard, On Tue, 1 Jan 2019 at 07:26, Richard O'Keefe wrote: > > ... > > To get an example, I did (String allSelectors atRandom), getting > #copyWithoutAll:. That has only one definition, in Collection: >copyWithoutAll: aCollection > "Answer a copy of the receiver that does not contain any elements > equal to those in aCollection." > > ^ self reject: [:each | aCollection includes: each] > > The comment simply paraphrases the rather simple code. I agree with pretty much everything you've written, but have a slightly different view here. Including what the method does, even when the code is fairly simple (OK, not getter / setter methods), is still useful. If the comment is absent, I have to look at the code, figure out what it does, and then either figure out if that's what it is supposed to do, or just assume that I'm correct. Having to figure out whether I've interpreted the code correctly just increases the cognitive load. If the comment includes what it is supposed to do, I have a context in which to read and evaluate the code, and it becomes much less effort. Cheers, Alistair --- End Message ---
Re: [Pharo-dev] [Pharo-users] New book: Pharo with Style
--- Begin Message --- I’ve always felt the XP book nailed it - don’t use comments as a crutch to avoid fixing confusing code and don’t do work twice by simply writing a comment that says the same as the code. (You can of course try to write the comment and auto-generate the code, but we’ve tried that before). Smalltalk is an expressive language that should read like comments naturally - both with the name of a method, the variables and the statements in it. This leaves comments as a good place to tell a story about the wider context and where to look to get started or learn more. I think this is possibly where Documentor is going to help you navigate along the real code. Of course if after all of this you can’t figure out how to fix the code - then a comment is a good last resort. Tim Sent from my iPhone > On 1 Jan 2019, at 12:43, Alistair Grant wrote: > > Hi Richard, > >> On Tue, 1 Jan 2019 at 07:26, Richard O'Keefe wrote: >> >> ... >> >> To get an example, I did (String allSelectors atRandom), getting >> #copyWithoutAll:. That has only one definition, in Collection: >> copyWithoutAll: aCollection >> "Answer a copy of the receiver that does not contain any elements >> equal to those in aCollection." >> >> ^ self reject: [:each | aCollection includes: each] >> >> The comment simply paraphrases the rather simple code. > > I agree with pretty much everything you've written, but have a > slightly different view here. > > Including what the method does, even when the code is fairly simple > (OK, not getter / setter methods), is still useful. If the comment is > absent, I have to look at the code, figure out what it does, and then > either figure out if that's what it is supposed to do, or just assume > that I'm correct. Having to figure out whether I've interpreted the > code correctly just increases the cognitive load. If the comment > includes what it is supposed to do, I have a context in which to read > and evaluate the code, and it becomes much less effort. > > Cheers, > Alistair > --- End Message ---
Re: [Pharo-dev] [Pharo-users] New book: Pharo with Style
--- Begin Message --- Pharo Smalltalk Developers mailing list wrote > Including what the method does, even when the code is fairly simple > (OK, not getter / setter methods), is still useful. Yes, but... there is no free lunch. While there may be a benefit when the code and comment are freshly written and in sync, they are duplication which smells whether code or comment and it is all too easy for the code to be patched without updating the comment. Now that minor speedup turns into a more significant slowdown when a user blindly follows the now-wrong comment. This possibility is made more likely be the fact that a stale comment will not be picked up by the testing framework. - Cheers, Sean -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html --- End Message ---
Re: [Pharo-dev] [Pharo-users] New book: Pharo with Style
I've read the whole booklet and I'm happy to follow most, if not all, the guidelines. Kent Beck's book was influential on this. I have a few remarks, though... Guideline 2.2 Typed variables should mention only existing or loadable types in the system. E.g selectFrom: aDate to: anotherDate and not selectFrom: aBeginningDate to: anEndDate (where Beginning and EndDate are not classes in the system) This affects guideline 2.3 because it says aBinaryBlock and there is no BinaryBlock class. I would also add another guideline here for the use of the 'as' preffix, e.g. asDate, asString, etc. where "as" means a different representation of receiver. E.g. asString is okay, while asShortString is not, because there is no ShortString class. Guideline 2.6 Should be "Number of" or "Count"? E.g. numberOfSomething or somethingCount? I don't like using "of" "with" or similar prepositions to name variables and classes. Guideline 3.2 #beSuprised would be better than #lookSurprised and follows a used convention of using #beSomething, e.g. #beBinary, #beReadOnly, etc. In the Guideline 5.6 the examples are the same. Regards! Esteban A. Maringolo El mié., 2 ene. 2019 a las 2:33, Sean P. DeNigris via Pharo-dev (< pharo-dev@lists.pharo.org>) escribió: > Pharo Smalltalk Developers mailing list wrote > > Including what the method does, even when the code is fairly simple > > (OK, not getter / setter methods), is still useful. > > Yes, but... there is no free lunch. While there may be a benefit when the > code and comment are freshly written and in sync, they are duplication > which > smells whether code or comment and it is all too easy for the code to be > patched without updating the comment. Now that minor speedup turns into a > more significant slowdown when a user blindly follows the now-wrong > comment. > This possibility is made more likely be the fact that a stale comment will > not be picked up by the testing framework. > > > > - > Cheers, > Sean > -- > Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html > >
