<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;}
p.gmail-m1171120194745820496msonospacing, li.gmail-m1171120194745820496msonospacing, div.gmail-m1171120194745820496msonospacing
{mso-style-name:gmail-m_1171120194745820496msonospacing;
mso-margin-top-alt:auto;
margin-right:0in;
mso-margin-bottom-alt:auto;
margin-left: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">John,</p>
<p class="MsoNormal">Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:</p>
<p class="MsoNormal">1) creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)</p>
<p class="MsoNormal">2) only core developers could update trunk comments; I wouldn’t want to place that burden on anybody</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.</p>
<p class="MsoNormal"><o:p> </o:p></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:jrmaffeo@gmail.com">John-Reed Maffeo</a><br>
<b>Sent: </b>Monday, May 30, 2022 0:04<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>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt">jaromir,<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt">Who said comments should be terse and polished?
<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt">It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive
in my mind. <o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt">Why not put a usage example into comments or the body of the text itself?<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt"><o:p> </o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:12.0pt">- jrm<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div>
<p class="MsoNormal">On Sun, May 29, 2022 at 12:56 PM Jaromir Matas <<a href="mailto:mail@jaromir.net">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 class="gmail-m1171120194745820496msonospacing"><span lang="CS">--</span></p>
<p class="gmail-m1171120194745820496msonospacing"><strong><span style="font-family:"Calibri Light",sans-serif;color:#333333;font-weight:normal">Jaromír Matas</span></strong></p>
<p class="gmail-m1171120194745820496msonospacing"><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>
<p class="MsoNormal"><o:p> </o:p></p>
</blockquote>
</div>
<p class="MsoNormal"><br clear="all">
<br>
-- <o:p></o:p></p>
<p class="MsoNormal">John-Reed Maffeo<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>