<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;}
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 Karl,</p>
<p class="MsoNormal">Yes, such links in comments would be great; the link in your example points to the same place as when you right-click a class and select ‘browse documentation’: it’s a collection of all first comments from every method. Such info doesn’t
 seem to me very useful but if the link opened a more detailed info about a method – that would be exactly it – and accessible via a similar link that you provided.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Btw, when you place the link inside the Browser and click on it, the Help window will open *<b>behind</b>* the browser window… probably a bug somewhere (not in your changeset, I mean).</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I’m going to take a look at the class ObjectWithDocumentation Chris suggested; however after a quick glance I have no idea where to start, what the class is supposed to do, what the entry points are etc – I haven’t noticed any documentation
<span style="font-family:"Segoe UI Emoji",sans-serif">😃</span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thanks for your input!</p>
<p class="MsoNormal">Best,</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>
<hr style="display:inline-block;width:98%" tabindex="-1">
<div id="divRplyFwdMsg" dir="ltr"><font face="Calibri, sans-serif" style="font-size:11pt" color="#000000"><b>From:</b> Squeak-dev <squeak-dev-bounces@lists.squeakfoundation.org> on behalf of karl ramberg <karlramberg@gmail.com><br>
<b>Sent:</b> Saturday, June 4, 2022 6:55:13 PM<br>
<b>To:</b> ma.chris.m@gmail.com <ma.chris.m@gmail.com>; The general-purpose Squeak developers list <squeak-dev@lists.squeakfoundation.org><br>
<b>Subject:</b> Re: [squeak-dev] Note sharing inside Squeak?</font>
<div> </div>
</div>
<div>
<div dir="ltr">
<div>Here is small change set that make links that open a HelpBrowser on a class.</div>
<div>Preferably the class is a help topic like TerseGuideHelp</div>
<div><br>
</div>
<div>Example:<br>
TerseGuideHelp Help<br>
Select text, press Alt+5 (CMD on Mac) and select 'Link to help on class'</div>
<div><br>
</div>
<div>Best,</div>
<div>Karl<br>
</div>
</div>
<br>
<div class="x_gmail_quote">
<div dir="ltr" class="x_gmail_attr">On Sat, Jun 4, 2022 at 3:36 AM Chris Muller <<a href="mailto:asqueaker@gmail.com">asqueaker@gmail.com</a>> wrote:<br>
</div>
<blockquote class="x_gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left:1px solid rgb(204,204,204); padding-left:1ex">
<div dir="ltr">
<div>Hi again Jaromir,</div>
<div><br>
</div>
<div>I didn't expect to have this much input on this topic but..  :)   I just accidentally stumbled upon ObjectWithDocumentation and its subclass hierarchy in the base image!  Check out its class comment:</div>
<div><br>
</div>
<div>____<br>
</div>
<div>ObjectWithDocumentation - an abstract superclass for objects that allows maintenance of an authoring stamp, a body of documentation, and a properties dictionary.<br>
</div>
<div>____</div>
<div><br>
</div>
<div>It has a subclass called MethodInterface.  They're in the "Protocols" category.  Maybe this is the "model" you're looking for, I don't know.</div>
<div><br>
</div>
<div>Wow, it looks like it's been there since near the beginning (2001), amazing how I stumble on "new" novel stuff like this after 20+ years of  Squeaking.</div>
<div><br>
</div>
<div> - Chris</div>
</div>
<br>
<div class="x_gmail_quote">
<div dir="ltr" class="x_gmail_attr">On Fri, Jun 3, 2022 at 10:27 AM Jaromir Matas <<a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a>> wrote:<br>
</div>
<blockquote class="x_gmail_quote" style="margin:0px 0px 0px 0.8ex; border-left:1px solid rgb(204,204,204); padding-left:1ex">
<div lang="EN-US">
<div>
<p class="x_MsoNormal">Hi Marcel,</p>
<p class="x_MsoNormal">I guess it’s true; I'll try what you suggested - to write a detailed info in the Squeak Help and place an entry line to open the topic in the method to see how feasible this is. It's an unchartered territory for me but fortunately there's
 the Help on Help topic :)</p>
<p class="x_MsoNormal">Thanks,</p>
<p class="x_MsoNormal">Jaromir</p>
<p class="x_MsoNormal"><u></u> <u></u></p>
<div style="border-color:rgb(225,225,225) currentcolor currentcolor; border-style:solid none none; border-width:1pt medium medium; padding:3pt 0in 0in">
<p class="x_MsoNormal" style="border:medium none; padding:0in"><b>From: </b><a href="mailto:marcel.taeumel@hpi.de" target="_blank">Marcel Taeumel</a><br>
<b>Sent: </b>Friday, June 3, 2022 17:01<br>
<b>To: </b><a href="mailto:squeak-dev@lists.squeakfoundation.org" target="_blank">squeak-dev</a><br>
<b>Subject: </b>Re: [squeak-dev] Note sharing inside Squeak?</p>
</div>
<p class="x_MsoNormal"><u></u> <u></u></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Hi Karl --<u></u><u></u></span></p>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> But we still don't have good documentation.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Because there are not a lot of people willing to write (extensive) documentation. This is not primarily a matter of where to put those comments. There are many options,
 all of them are valid:<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- Commentary in the method<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- Extra commentary method<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- Class comment<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- Help topic<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">All these places can be found with Squeak's image-wide text search.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Best,<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Marcel<u></u><u></u></span></p>
</div>
<blockquote style="border-color:currentcolor currentcolor currentcolor windowtext; border-style:none none none solid; border-width:medium medium medium 1pt; padding:0in 0in 0in 8pt; margin-left:0in; margin-top:15pt; margin-bottom:5pt; min-width:500px">
<p style="margin-top:7.5pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:rgb(170,170,170)">Am 02.06.2022 22:42:54 schrieb karl ramberg <<a href="mailto:karlramberg@gmail.com" target="_blank">karlramberg@gmail.com</a>>:<u></u><u></u></span></p>
<div>
<div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">This story is repeated so often. But we still don't have good documentation.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Or what we have is not very accessible.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">I remember struggling quite a bit before grasping the Squeak/ Smalltalk way of working.
<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">But once I got the hang of it, suddenly a whole lot of stuff  made sense all at once. That is part of what makes this so hard to document. It is not linear learning,
 it's exponential.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Best,<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Karl
<u></u><u></u></span></p>
</div>
</div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
<div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">On Thu, Jun 2, 2022 at 9:16 PM Jaromir Matas <<a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a>> wrote:<u></u><u></u></span></p>
</div>
<blockquote style="border-color:currentcolor currentcolor currentcolor rgb(204,204,204); border-style:none none none solid; border-width:medium medium medium 1pt; padding:0in 0in 0in 6pt; margin-left:4.8pt; margin-right:0in; min-width:500px">
<div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Hi Chris, Marcel, Tim, John, all:<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Thanks very much for all your thoughts. There seem to be a few distinct "types" of comments:<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- "first comments" (the terse and polished) in each method are treated differently, e.g. the "browse documentation" class menu item extracts them from all methods
 into a summary document<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- "one liner" comments sprinkled around the code to help reading the code (Chris's examples, not to be overused)<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- "documentation" comments with detailed imlementation or other info (desirable but swamping the method and forcing one to scroll...)<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">- plus surely some not so distinct<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">I have a suggestion:<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">I'd try to make my first comment as terse and polished as my language skills allow and I'd put my additional implementation notes and examples behind the code with
 the heading: 'Documentation'. It should hint you don't necessarily need to bother read it but it'd be there for a potential reader or for possible future placing it to an external documentation platform like Squeak Help. Does it make sense? Is it feasible
 such external Squeak Help notes "repository" accessible via e.g. method “browse documentation” menu item would ever be setup or is it just a fantasy? (I have no idea how difficult this could be)<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">When I learned Squeak I badly missed some more detailed info about methods and classes (e.g. class "entry points" like how to open any tool that is not in Squeak's
 menu somewhere). General Smalltalk literature is no replacement for such info. And especially when debugging, more detailed implementation info could be priceless :) (at least for a beginner)<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Thanks again,<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Jaromir<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p><span lang="CS" style="font-size:10pt; font-family:Arial,sans-serif; color:black">--</span><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><strong><span style="font-size:10pt; font-family:"Calibri Light",sans-serif; color:rgb(51,51,51); font-weight:normal">Jaromír Matas</span></strong><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><span style="font-size:10pt; font-family:"Calibri Light",sans-serif; color:rgb(46,117,182)"><a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a></span><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<div style="border-color:currentcolor; border-style:solid none none; border-width:1pt medium medium; padding:3pt 0in 0in">
<p class="x_MsoNormal"><b><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">From:
</span></b><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><a href="mailto:mail@jaromir.net" target="_blank">Jaromir Matas</a><br>
<b>Sent: </b>Wednesday, June 1, 2022 20:07<br>
<b>To: </b><a href="mailto:ma.chris.m@gmail.com" target="_blank">ma.chris.m@gmail.com</a>;
<a href="mailto:squeak-dev@lists.squeakfoundation.org" target="_blank">The general-purpose Squeak developers list</a><br>
<b>Subject: </b>Re: [squeak-dev] Note sharing inside Squeak?<u></u><u></u></span></p>
</div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Hi Chris,<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> 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. 
<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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?)<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> 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.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> 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.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> 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".<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> [...]<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">> I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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.<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Thanks for your comments!<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">best,<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Jaromir<u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p><span lang="CS" style="font-size:10pt; font-family:Arial,sans-serif; color:black">--</span><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><strong><span style="font-size:10pt; font-family:"Calibri Light",sans-serif; color:rgb(51,51,51); font-weight:normal">Jaromír Matas</span></strong><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><span style="font-size:10pt; font-family:"Calibri Light",sans-serif; color:rgb(46,117,182)"><a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a></span><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<div style="border-color:currentcolor; border-style:solid none none; border-width:1pt medium medium; padding:3pt 0in 0in">
<p class="x_MsoNormal"><b><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">From:
</span></b><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><a href="mailto:asqueaker@gmail.com" target="_blank">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" target="_blank">The general-purpose Squeak developers list</a><br>
<b>Subject: </b>Re: [squeak-dev] Note sharing inside Squeak?<u></u><u></u></span></p>
</div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Hi Jaromir,<u></u><u></u></span></p>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><i><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Documentation</span></i><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> 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.<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Best,<u></u><u></u></span></p>
</div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">  Chris<u></u><u></u></span></p>
</div>
</div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<div>
<div>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">On Sun, May 29, 2022 at 2:56 PM Jaromir Matas <<a href="mailto:mail@jaromir.net" target="_blank">mail@jaromir.net</a>> wrote:<u></u><u></u></span></p>
</div>
<blockquote style="border-color:currentcolor currentcolor currentcolor rgb(204,204,204); border-style:none none none solid; border-width:medium medium medium 1pt; padding:0in 0in 0in 6pt; margin:5pt 0in 5pt 4.8pt; min-width:500px">
<div>
<div>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Hi all,<u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">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…<u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Any suggestion welcome :)<u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Best,<u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black">Jaromir<u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p><span lang="CS" style="font-size:10pt; font-family:Arial,sans-serif; color:black">--</span><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><strong><span style="font-size:10pt; font-family:"Calibri Light",sans-serif; color:rgb(51,51,51); font-weight:normal">Jaromír Matas</span></strong><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u><u></u></span></p>
<p><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><a href="mailto:mail@jaromir.net" target="_blank"><span style="font-family:"Calibri Light",sans-serif">mail@jaromir.net</span></a><u></u><u></u></span></p>
<p class="x_MsoNormal" style="margin-left:9.6pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
</div>
</blockquote>
</div>
<p class="x_MsoNormal" style="margin-left:4.8pt"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
<p class="x_MsoNormal"><span style="font-size:10pt; font-family:Arial,sans-serif; color:black"> <u></u><u></u></span></p>
</div>
</div>
</blockquote>
</div>
</div>
</blockquote>
<p class="x_MsoNormal" style="margin-right:0.5in; margin-bottom:5pt; margin-left:4.8pt">
<span style="font-size:10pt; font-family:Arial,sans-serif; color:black"><u></u> <u></u></span></p>
<p class="x_MsoNormal"><u></u> <u></u></p>
</div>
</div>
<br>
</blockquote>
</div>
<br>
</blockquote>
</div>
</div>
</body>
</html>