[squeak-dev] Note sharing inside Squeak?

Chris Muller asqueaker at gmail.com
Wed Jun 1 02:48:31 UTC 2022

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
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?"*
               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>

More information about the Squeak-dev mailing list