[squeak-dev] Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)
asqueaker at gmail.com
Wed Aug 7 04:30:29 UTC 2019
> Changing the subject line.
> 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.
> > Here's where I'm going: "built-in documentation". For all
> > 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
> > 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
> > 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
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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Squeak-dev