<div dir="ltr"><div dir="ltr"></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>Changing the subject line.<br></blockquote><div><br></div><div>Thank you!</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
On Mon, Aug 05, 2019 at 11:59:32PM -0500, Chris Muller wrote:<br>
> Hi there, as we go to fix comments, may we take the opportunity to see if<br>
> we'd like to change the nature of the comment in general?<br>
<br>
I think it's a good idea to have better built-in documentation. I also<br>
know that it can be a lot of work, and somebody has to be willing and<br>
able to put the time and effort into making it happen. An unmaintained<br>
set of documentation can be worse than none at all.<br></blockquote><div><br></div><div>Yes.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
> <br>
> Here's where I'm going:  "built-in documentation".  For all #firstComments<br>
> anyway, in methods throughout the system, if we would direct those<br>
> particular comments toward the *Dynabook user*, something like:<br>
> <br>
>    "Answer whether the receiver can be sent a message named aSymbol."<br>
<br>
I tried exploring this:<br>
<br>
   Object selectors collect: [ :sel | sel -> (Object firstCommentAt: sel) ]<br>
<br>
The results suggest that the firstComment strings, when viewed outside the<br>
context of a system browser, are not very meaningful.\<br></blockquote><div><br></div><div>Yes, context is everything.</div><div><br></div><div>  A developer reading code in a system browser, </div><div>  a data engineer using a query language that wraps a Smalltalk API,</div><div>  or a user using a thin layer UI interface that wraps a Smalltalk API</div><div><br></div><div>In those contexts, firstComments could be given extra care to explain the usage of the method, instead of its code.<br></div><div><br></div><div>Note the proposal is only for public methods.<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
> <br>
> then relatively simple systems can easily extract it to help connect users<br>
> to a Dynabook experience.  Separate comments can be used to describe the<br>
> 'dictionarys' or whatever implementation if desired, but since they<br>
> wouldn't be the #firstComment, they wouldn't be presented in the user layer.<br>
> <br>
> It's a simple but powerful leverage, what do you think?<br>
<br>
I like the idea in principle, but in practice I would prefer to see energy<br>
going into the Squeak help system, and possibly also into the built in<br>
hyperlinking that can be embedded in existing comments. The help system<br>
seems most promising to me overall, because it already has nice hooks<br>
for displaying the organization and comments of exiting classes and<br>
methods, and the help browser itself feels familiar and easy to use.<br></blockquote><div><br></div><div>I think the help system is great and would also like to see more things there.</div><div><br></div><div>This is just a suggestion for Smalltalk developers to consider adopting as a practice when already writing their next firstComment of a method.  Systems nowadays are including "metadata".  I know we have Pragmas but that's a big project like what you were alluding to.  If this caught on as a good Smalltalk practice, over time, these comments could become very useful in those aforementioned contexts.</div><div><br></div><div>Best,</div><div>  Chris</div><div> </div></div></div>