[squeak-dev] Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)

Chris Muller asqueaker at gmail.com
Wed Aug 7 04:30:29 UTC 2019


>
> Changing the subject line.
>

Thank you!


>
> On Mon, Aug 05, 2019 at 11:59:32PM -0500, Chris Muller wrote:
> > Hi there, as we go to fix comments, may we take the opportunity to see if
> > we'd like to change the nature of the comment in general?
>
> I think it's a good idea to have better built-in documentation. I also
> know that it can be a lot of work, and somebody has to be willing and
> able to put the time and effort into making it happen. An unmaintained
> set of documentation can be worse than none at all.
>

Yes.


>
> >
> > Here's where I'm going:  "built-in documentation".  For all
> #firstComments
> > anyway, in methods throughout the system, if we would direct those
> > particular comments toward the *Dynabook user*, something like:
> >
> >    "Answer whether the receiver can be sent a message named aSymbol."
>
> I tried exploring this:
>
>    Object selectors collect: [ :sel | sel -> (Object firstCommentAt: sel) ]
>
> The results suggest that the firstComment strings, when viewed outside the
> context of a system browser, are not very meaningful.\
>

Yes, context is everything.

  A developer reading code in a system browser,
  a data engineer using a query language that wraps a Smalltalk API,
  or a user using a thin layer UI interface that wraps a Smalltalk API

In those contexts, firstComments could be given extra care to explain the
usage of the method, instead of its code.

Note the proposal is only for public methods.


> >
> > then relatively simple systems can easily extract it to help connect
> users
> > to a Dynabook experience.  Separate comments can be used to describe the
> > 'dictionarys' or whatever implementation if desired, but since they
> > wouldn't be the #firstComment, they wouldn't be presented in the user
> layer.
> >
> > It's a simple but powerful leverage, what do you think?
>
> I like the idea in principle, but in practice I would prefer to see energy
> going into the Squeak help system, and possibly also into the built in
> hyperlinking that can be embedded in existing comments. The help system
> seems most promising to me overall, because it already has nice hooks
> for displaying the organization and comments of exiting classes and
> methods, and the help browser itself feels familiar and easy to use.
>

I think the help system is great and would also like to see more things
there.

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.

Best,
  Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20190806/bc9f785a/attachment.html>


More information about the Squeak-dev mailing list