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

Hi Richard,

...

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