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.

Best,
Karl



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