Hi Jaromir,

I just remembered one more technique a guy I worked with a long time ago
would do that I wanted to share.  For long, complex methods, he would
intersperse little one-liner comments that would "translate" the next line
of code to a way that, when read collectively, would basically describe
what the method does in prose.  He would write conditionals as a question,
and then "answer the question".

For example, I picked a method at random in the image and rewrote it in his
style:
____
detectMin: aBlock
     "Evaluate aBlock with each of the receiver's elements as the argument.
     Answer the element for which aBlock evaluates to the lowest number.
     If collection empty, return nil."

     | minElement minValue |
    * "enumerate my elements"*
     self do: [:each | | val |
          *"has a current minimum already been established?"*
          minValue
               ifNotNil: [ *"yes, does the current element compute less?"*
                    (val := aBlock value: each) < minValue
                         ifTrue: [ *"yes, assign the new minimum"*
                              minElement := each.
                              minValue := val ] ]
               ifNil: [ *"no.  Establish current as the minimum"*
                    minElement := each.
                    minValue := aBlock value: each ] ].
*     "Answer the element that computed the minimum value."*
     ^ minElement
____

This was in Java, which doesn't read as well, so I actually found his
technique helpful when reading his code.  I'm dubious, though, that this
would be a good practice in Smalltalk code except in rare circumstances.

 - 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/b769f498/attachment.html>