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

[Alistair Grant via Pharo-dev]

--- Begin Message ---

Hi Richard,

On Tue, 1 Jan 2019 at 07:26, Richard O'Keefe <rao...@gmail.com> 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 ---