<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"Calibri Light";
panose-1:2 15 3 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
p.MsoNoSpacing, li.MsoNoSpacing, div.MsoNoSpacing
{mso-style-priority:1;
margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
.MsoChpDefault
{mso-style-type:export-only;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="#954F72" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal">Hi Chris,</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> I like to consider the bridge between the code and the user. By this, and recognizing that methods can have multiple comments, the first method comment could be classified as "special" from the sense that UI's might consume and show
it to end users, and would be written under that assumption. </p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Yes, I've just noticed there's a 'browse documentation' item on the class menu (right-click) in the Browser that extracts all first comments from every method in that class into a document. So I agree the first comment should summarize
the function of the method in a terse and polished way. It's the WHAT the method does; the HOW can/should come after that imo. Such a menu item available for each method could be the interface (the question is interface to what and how would the notes be entered
- via Inbox? Approved by somebody or uncensored?)</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> I do think it's essential for comments to be as terse and polished as they can. I don't know if it was part of the original spirit of Smalltalk in the 1980's but, at least in the 1990's, my mentors, including Ward Cunningham, taught
that long comments are generally detrimental. Specifically, they can be very helpful. But long comments on every method causes constant scrolling to be required, increasing the physical and mental effort needed to do development. They argued that if so
much prose is needed just to describe the method, the code should be improved instead.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">That's good :) I've managed to write a 7 line long method with 22 lines of comments and honestly, I read them each time I want to remember how it works :) (Needless to say I have no idea how to improve it.) But I suspect this probably falls
into the 'documentation' category... That's why my original question; I'd like to record somewhere all the notes that explain each dangerous step, examples, references to tests, external references to discussion etc. - without swamping the method.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> Documentation is something that can and should be separate, I don't think people should have to come all the way into to the code to find documentation, so I love Tim's idea to support links out to Squeak's Help system from within the
methods. A seamless bridge out to the documentation, so method comments can be talking about mechanics of the method. Beautiful idea.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Yes, if there was an easy path from each method to to a documentation place, all the implementation details could go there and the method could only contain comments important for general understanding of its function. By details I mean
e.g. why this nil check is important, what situations are not covered, how the method improves the previous version, interrelations with other methods etc.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> 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".</p>
<p class="MsoNormal">> [...]</p>
<p class="MsoNormal">> I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Yes, sometimes it's key; e.g. to point out that at this exact place in the code we assume/know this and this. In Smalltalk, I agree, it may be distracting if overused.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thanks for your comments!</p>
<p class="MsoNormal">best,</p>
<p class="MsoNormal">Jaromir</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNoSpacing"><span lang="CS">--</span></p>
<p class="MsoNoSpacing"><strong><span style="font-family:"Calibri Light",sans-serif;color:#333333;font-weight:normal">Jaromír Matas</span></strong><span style="font-family:"Calibri Light",sans-serif;color:#555555"><o:p></o:p></span></p>
<p class="MsoNoSpacing"><span style="font-family:"Calibri Light",sans-serif;color:#2E75B6">mail@jaromir.net</span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div style="mso-element:para-border-div;border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="border:none;padding:0in"><b>From: </b><a href="mailto:asqueaker@gmail.com">Chris Muller</a><br>
<b>Sent: </b>Tuesday, May 31, 2022 23:02<br>
<b>To: </b><a href="mailto:squeak-dev@lists.squeakfoundation.org">The general-purpose Squeak developers list</a><br>
<b>Subject: </b>Re: [squeak-dev] Note sharing inside Squeak?</p>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal">Hi Jaromir,<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">I like to consider the bridge between the code and the user. By this, and recognizing that methods can have multiple comments, the first method comment could be classified as "special" from the sense that UI's might consume and show it
to end users, and would be written under that assumption. Then, the 2nd comment and beyond comments would be the ones talking to readers of the
<i>code</i> (developers). Also, that first comment (the UI comment) could even, for example, identify the argument types and return type in some standard <i>syntax</i>, that might even be processable -- although that might be handled better with a pragma.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">I do think it's essential for comments to be as terse and polished as they can. I don't know if it was part of the original spirit of Smalltalk in the 1980's but, at least in the 1990's, my mentors, including Ward Cunningham, taught that
long comments are generally detrimental. Specifically, they can be very helpful. But long comments on every method causes constant scrolling to be required, increasing the physical and mental effort needed to do development. They argued that if so much
prose is needed just to describe the method, the code should be improved instead.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal"><i>Documentation</i> is something that can and should be separate, I don't think people should have to come all the way into to the code to find documentation, so I love Tim's idea to support links out to Squeak's Help system from within
the methods. A seamless bridge out to the documentation, so method comments can be talking about mechanics of the method. Beautiful idea.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Best,<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> Chris<o:p></o:p></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div>
<p class="MsoNormal">On Sun, May 29, 2022 at 2:56 PM Jaromir Matas <<a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a>> wrote:<o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">Hi all,</p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">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" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">Any suggestion welcome :)</p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">Best,</p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">Jaromir</p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"> </p>
<p><span lang="CS">--</span></p>
<p><strong><span style="font-family:"Calibri Light",sans-serif;color:#333333;font-weight:normal">Jaromír Matas</span></strong></p>
<p><span style="font-family:"Calibri Light",sans-serif;color:#2E75B6"><a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a></span></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"> </p>
</div>
</div>
</blockquote>
</div>
<p class="MsoNormal" style="margin-left:4.8pt"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>