<div dir="ltr"><div dir="ltr"><div class="gmail_default" style="font-size:small"><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jun 27, 2022 at 10:44 AM karl ramberg <<a href="mailto:karlramberg@gmail.com">karlramberg@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>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.</div><div>A way of skipping whole lines like C style // single line comment could maybe help with that.</div></div></blockquote><div><br></div><div class="gmail_default" style="font-size:small">If I was going to hack a solution to this I'd implement the following on " enclose/remove.</div><div class="gmail_default" style="font-size:small">On enclose replace matching pairs of "'s with `` (two back ticks) & '' (two forward ticks).</div><div class="gmail_default" style="font-size:small">On remove, replace matching pairs of `` & '' with pairs of "s.</div><div class="gmail_default" style="font-size:small"><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>Best,<br></div><div>Karl</div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jun 1, 2022 at 4:49 AM Chris Muller <<a href="mailto:asqueaker@gmail.com" target="_blank">asqueaker@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex"><div dir="ltr">Hi Jaromir,<div><br></div><div>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".</div><div><br></div><div>For example, I picked a method at random in the image and rewrote it in his style:</div><div>____</div><div>detectMin: aBlock<br>     "Evaluate aBlock with each of the receiver's elements as the argument. <br>     Answer the element for which aBlock evaluates to the lowest number.<br>     If collection empty, return nil."<br><br>     | minElement minValue |<br>    <b> "enumerate my elements"</b><br>     self do: [:each | | val | <br>          <b>"has a current minimum already been established?"</b><br>          minValue<br>               ifNotNil: [ <b>"yes, does the current element compute less?"</b><br>                    (val := aBlock value: each) < minValue<br>                         ifTrue: [ <b>"yes, assign the new minimum"</b><br>                              minElement := each.<br>                              minValue := val ] ]<br>               ifNil: [ <b>"no.  Establish current as the minimum"</b><br>                    minElement := each.<br>                    minValue := aBlock value: each ] ].</div><div><b>     "Answer the element that computed the minimum value."</b><br>     ^ minElement<br></div><div>____</div><div><br></div><div>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.<br></div><div><br></div><div> - Chris</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, May 29, 2022 at 2:56 PM Jaromir Matas <<a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">





<div lang="EN-US">
<div>
<p class="MsoNormal">Hi all,</p>
<p class="MsoNormal">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…</p>
<p class="MsoNormal">Any suggestion welcome :)</p>
<p class="MsoNormal">Best,</p>
<p class="MsoNormal">Jaromir</p>
<p class="MsoNormal"><u></u> <u></u></p>
<p><span lang="CS">--</span></p>
<p><strong><span style="font-family:"Calibri Light",sans-serif;color:rgb(51,51,51);font-weight:normal">Jaromír Matas</span></strong><span style="font-family:"Calibri Light",sans-serif;color:rgb(85,85,85)"><u></u><u></u></span></p>
<p><span style="font-family:"Calibri Light",sans-serif;color:rgb(46,117,182)"><a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a></span></p>
<p class="MsoNormal"><u></u> <u></u></p>
</div>
</div>

<br>
</blockquote></div></div>
<br>
</blockquote></div>
<br>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><span style="font-size:small;border-collapse:separate"><div>_,,,^..^,,,_<br></div><div>best, Eliot</div></span></div></div></div></div>