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

[Tim Mackinnon via Pharo-users]

--- 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 <akgrant0...@gmail.com> wrote:
> 
> 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 ---