[squeak-dev] Note sharing inside Squeak?
karlramberg at gmail.com
Mon Jun 27 17:44:10 UTC 2022
One issue I have with lots of inline comments like here is that it makes it
really painful if you want to comment out a section of the code for
debugging, testing etc.
A way of skipping whole lines like C style // single line comment could
maybe help with that.
On Wed, Jun 1, 2022 at 4:49 AM Chris Muller <asqueaker at gmail.com> wrote:
> 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
> 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 :)
>> *Jaromír Matas*
>> mail at jaromir.net
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Squeak-dev