Hi Jaromir,

I like to consider the bridge between the code and the user.  By this, and
recognizing that methods can have multiple comments, the first method
comment could be classified as "special" from the sense that UI's might
consume and show it to end users, and would be written under that
assumption.  Then, the 2nd comment and beyond comments would be the ones
talking to readers of the *code* (developers).  Also, that first comment
(the UI comment) could even, for example, identify the argument types and
return type in some standard *syntax*, that might even be processable --
although that might be handled better with a pragma.

I do think it's essential for comments to be as terse and polished as they
can.  I don't know if it was part of the original spirit of Smalltalk in
the 1980's but, at least in the 1990's, my mentors, including Ward
Cunningham, taught that long comments are generally detrimental.
Specifically, they can be very helpful.  But long comments on every method
causes constant scrolling to be required, increasing the physical and
mental effort needed to do development.  They argued that if so much prose
is needed just to describe the method, the code should be improved instead.

*Documentation* is something that can and should be separate, I don't think
people should have to come all the way into to the code to find
documentation, so I love Tim's idea to support links out to Squeak's Help
system from within the methods.  A seamless bridge out to the
documentation, so method comments can be talking about mechanics of the
method.  Beautiful idea.

Best,
  Chris

On Sun, May 29, 2022 at 2: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
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220531/d10bd034/attachment.html>