Smalltalk › Pharo › Pharo Smalltalk Developers

New book: Pharo with Style

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

10 messages Options

Stephane Ducasse-3

New book: Pharo with Style

Hello Fellow Pharoers

I'm happy to announce a new little book to improve the culture around Pharo.
I will revise it in the future so you can feel free to send feedback
and pull requests
to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle

Stef

"The best way to predict the future is to invent" so I do it.

withstylebook.pdf (346K) Download Attachment

Pharo Smalltalk Developers mailing list

Re: New book: Pharo with Style

On 2018-12-30 16:13, Stephane Ducasse wrote:

> Hello Fellow Pharoers
>
> I'm happy to announce a new little book to improve the culture around Pharo.
> I will revise it in the future so you can feel free to send feedback
> and pull requests
> to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle
>
> Stef
>
> "The best way to predict the future is to invent" so I do it.

Stéphane,

You'll find, attached, a revised PDF version with my comments.

--
-----------------
Benoît St-Jean
Yahoo! Messenger: bstjean
Twitter: @BenLeChialeux
Pinterest: benoitstjean
Instagram: Chef_Benito
IRC: lamneth
Blogue: endormitoire.wordpress.com
"A standpoint is an intellectual horizon of radius zero". (A. Einstein)

bstj_revised_withStyle-wip.pdf (286K) Download Attachment

Stephane Ducasse-3

Re: New book: Pharo with Style

In reply to this post by Stephane Ducasse-3

Thanks! Thanks!
I will go over it (now laying on my back :(( stupid muscles strike back!)

On Mon, Dec 31, 2018 at 2:18 AM Benoit St-Jean <[hidden email]> wrote:

>
> On 2018-12-30 16:13, Stephane Ducasse wrote:
> > Hello Fellow Pharoers
> >
> > I'm happy to announce a new little book to improve the culture around Pharo.
> > I will revise it in the future so you can feel free to send feedback
> > and pull requests
> > to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle
> >
> > Stef
> >
> > "The best way to predict the future is to invent" so I do it.
>
> Stéphane,
>
> You'll find, attached, a revised PDF version with my comments.
>
>
>
> --
> -----------------
> Benoît St-Jean
> Yahoo! Messenger: bstjean
> Twitter: @BenLeChialeux
> Pinterest: benoitstjean
> Instagram: Chef_Benito
> IRC: lamneth
> Blogue: endormitoire.wordpress.com
> "A standpoint is an intellectual horizon of radius zero". (A. Einstein)
>

Pharo Smalltalk Developers mailing list

Re: New book: Pharo with Style

Besides, I forgot to add one comment : you should have guidelines for
protocol naming. It's not critical per se but I find it quite annoying
to look for stuff in "enumerating" when it's been put in "printing" ! loll

On 2018-12-31 03:51, Stephane Ducasse wrote:

> Thanks! Thanks!
> I will go over it (now laying on my back :(( stupid muscles strike back!)
>
> On Mon, Dec 31, 2018 at 2:18 AM Benoit St-Jean <[hidden email]> wrote:
>> On 2018-12-30 16:13, Stephane Ducasse wrote:
>>> Hello Fellow Pharoers
>>>
>>> I'm happy to announce a new little book to improve the culture around Pharo.
>>> I will revise it in the future so you can feel free to send feedback
>>> and pull requests
>>> to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle
>>>
>>> Stef
>>>
>>> "The best way to predict the future is to invent" so I do it.
>> Stéphane,
>>
>> You'll find, attached, a revised PDF version with my comments.
>>
>>
>>
>> --
>> -----------------
>> Benoît St-Jean
>> Yahoo! Messenger: bstjean
>> Twitter: @BenLeChialeux
>> Pinterest: benoitstjean
>> Instagram: Chef_Benito
>> IRC: lamneth
>> Blogue: endormitoire.wordpress.com
>> "A standpoint is an intellectual horizon of radius zero". (A. Einstein)
>>

--
-----------------
Benoît St-Jean
Yahoo! Messenger: bstjean
Twitter: @BenLeChialeux
Pinterest: benoitstjean
Instagram: Chef_Benito
IRC: lamneth
Blogue: endormitoire.wordpress.com
"A standpoint is an intellectual horizon of radius zero". (A. Einstein)

Pharo Smalltalk Developers mailing list

Re: [Pharo-users] New book: Pharo with Style

In reply to this post by Stephane Ducasse-3

Hi Richard,

On Tue, 1 Jan 2019 at 07:26, Richard O'Keefe <[hidden email]> 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

Pharo Smalltalk Developers mailing list

Re: [Pharo-users] New book: Pharo with Style

In reply to this post by Stephane Ducasse-3

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 <[hidden email]> wrote:
>
> Hi Richard,
>
>> On Tue, 1 Jan 2019 at 07:26, Richard O'Keefe <[hidden email]> 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
>

Pharo Smalltalk Developers mailing list

Re: New book: Pharo with Style

In reply to this post by Stephane Ducasse-3

That is a useful contribution, thank you (again) for your efforts !

> On 30 Dec 2018, at 22:13, Stephane Ducasse <[hidden email]> wrote:
>
> Hello Fellow Pharoers
>
> I'm happy to announce a new little book to improve the culture around Pharo.
> I will revise it in the future so you can feel free to send feedback
> and pull requests
> to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle
>
> Stef
>
> "The best way to predict the future is to invent" so I do it.
> <withstylebook.pdf>

Pharo Smalltalk Developers mailing list

Re: New book: Pharo with Style

In reply to this post by Stephane Ducasse-3

Nice work.

Doru

> On Dec 30, 2018, at 10:13 PM, Stephane Ducasse <[hidden email]> wrote:
>
> Hello Fellow Pharoers
>
> I'm happy to announce a new little book to improve the culture around Pharo.
> I will revise it in the future so you can feel free to send feedback
> and pull requests
> to https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle
>
> Stef
>
> "The best way to predict the future is to invent" so I do it.
> <withstylebook.pdf>

--
www.feenk.com

"To utilize feedback, you first have to acquire it."

Pharo Smalltalk Developers mailing list

Re: [Pharo-users] New book: Pharo with Style

In reply to this post by Pharo Smalltalk Developers mailing list

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

Esteban A. Maringolo

Re: [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 (<[hidden email]>) 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