jaromir,

Who said comments should be terse and polished?

It would be more helpful to people like myself (still a nube after 30+
years) to see a long, complex entry into a method's comment than no comment
at all! Putting comments in some other place is counter productive in my
mind.

Why not put a usage example into comments or the body of the text itself?

- jrm

On Sun, May 29, 2022 at 12:56 PM Jaromir Matas <mail at jaromir.net> wrote:

> Hi all,
>
> In your experience, what would be a good place to *share* more detailed
> information about e.g. a method: like why I had to include this line and
> that check, which situations must be taken into account, alternative
> approaches, examples, references to tests etc etc. Ideally reachable from
> the image. Would such "notesharing" be welcome or rather confusing or even
> conterproductive? Often I forget why I did this and that and have to check
> my notes (if I'm lucky to have made them AND find them). I'm aware method
> comments are definitely not the place; they are meant to be rather terse
> and polished. Squeak wiki? Squeak Help? They’d have to be linked somehow to
> the methods, I imagine, to be useful in this regard…
>
> Any suggestion welcome :)
>
> Best,
>
> Jaromir
>
>
>
> --
>
> *Jaromír Matas*
>
> mail at jaromir.net
>
>
>
>

-- 
John-Reed Maffeo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220529/831ec026/attachment.html>