[squeak-dev] Note sharing inside Squeak?
asqueaker at gmail.com
Wed Jun 1 02:48:31 UTC 2022
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
"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."*
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.
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 :)
> *Jaromír Matas*
> mail at jaromir.net
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Squeak-dev