On Mon, Jun 27, 2022 at 10:44 AM karl ramberg <karlramberg at gmail.com> wrote:

> 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.
>

If I was going to hack a solution to this I'd implement the following on "
enclose/remove.
On enclose replace matching pairs of "'s with `` (two back ticks) & '' (two
forward ticks).
On remove, replace matching pairs of `` & '' with pairs of "s.

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
>>>
>>>
>>>
>>>
>>
>

-- 
_,,,^..^,,,_
best, Eliot
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220627/1cf35003/attachment.html>