The Inbox: Kernel-cmfcmf.1251.mcz
Locked
 
|
A new version of Kernel was added to project The Inbox:
http://source.squeak.org/inbox/Kernel-cmfcmf.1251.mcz ==================== Summary ==================== Name: Kernel-cmfcmf.1251 Author: cmfcmf Time: 5 August 2019, 4:39:08.95825 pm UUID: eb7ae4e2-7697-7745-b4c3-4f9ce5975e2b Ancestors: Kernel-mt.1250 Clarify comment in Object>>respondsTo: to indicate that the method can also be defined in a superclass. =============== Diff against Kernel-mt.1250 =============== Item was changed: ----- Method: Object>>respondsTo: (in category 'class membership') ----- + respondsTo: aSymbol + "Answer whether the method dictionary of the receiver's class or any of its superclasses contains - respondsTo: aSymbol - "Answer whether the method dictionary of the receiver's class contains aSymbol as a message selector." ^self class canUnderstand: aSymbol! |
Re: The Inbox: Kernel-cmfcmf.1251.mcz
|
|
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? 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." 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? Best, Chris On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> wrote: A new version of Kernel was added to project The Inbox: |
Re: The Inbox: Kernel-cmfcmf.1251.mcz
|
One can always send any message to any receiver. :-) The question is whether the answer can be meaningful or not. Can a client expect a meaningful answer from such a message send? Neither mentioning method dictionary nor superclasses help figure out when and why to send #respondsTo: to an object. Only Behavior is the domain and place to talk about method dictionary and superclasses. The comment in #canUnderstand: does already mention method dictionary and superclasses. Just my two cents. :-) Best, Marcel
|
Re: The Inbox: Kernel-cmfcmf.1251.mcz
|
|
On Tue, Aug 6, 2019 at 3:18 AM Marcel Taeumel <[hidden email]> wrote:
Sure, a Smalltalk developer gets that. But from the context of what's meaningful to a Dynabook user simply interested in using Squeak objects as an app, they simply know they don't want to see that "does not understand" error message. "Can send" is synonymous enough with that. But my main point is not about what exact words, but about the idea of speaking to that specific audience through the #firstComment.
Right. The thrust of my post is that the "client" in your statement above is a Dynabook user, and _not_ a Smalltalk developer.
Users are only concerned with "sending messages to objects", nothing else. Those Dictionary's are below the level of what they care about. Even the notion of inheritance (superclasses) will cause their eyes to glaze over. Sending messages to concrete instances is where the rubber meets the road. The #firstComment is a opportunity to open up the Squeak class-library to a new group of people, without affecting our ability to talk to Smalltalk developers in the 2nd - nth comments. But most of the time, I'm sure the one single user-centric comment is sufficient for both groups. - Chris
|
Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)
|
|
In reply to this post by Chris Muller-3
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 #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. > > 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. But overall: Good documentation is hard work, and it requires a lot of dedication to make it happen. Different tools might help, but at the end of the day somebody has to do the work. Dave > > Best, > Chris > > On Mon, Aug 5, 2019 at 9:39 AM <[hidden email]> wrote: > > > A new version of Kernel was added to project The Inbox: > > http://source.squeak.org/inbox/Kernel-cmfcmf.1251.mcz > > > > ==================== Summary ==================== > > > > Name: Kernel-cmfcmf.1251 > > Author: cmfcmf > > Time: 5 August 2019, 4:39:08.95825 pm > > UUID: eb7ae4e2-7697-7745-b4c3-4f9ce5975e2b > > Ancestors: Kernel-mt.1250 > > > > Clarify comment in Object>>respondsTo: to indicate that the method can > > also be defined in a superclass. > > > > =============== Diff against Kernel-mt.1250 =============== > > > > Item was changed: > > ----- Method: Object>>respondsTo: (in category 'class membership') ----- > > + respondsTo: aSymbol > > + "Answer whether the method dictionary of the receiver's class or > > any of its superclasses contains > > - respondsTo: aSymbol > > - "Answer whether the method dictionary of the receiver's class > > contains > > aSymbol as a message selector." > > > > ^self class canUnderstand: aSymbol! > > > > > > > |
Re: Dynabook comments (was: The Inbox: Kernel-cmfcmf.1251.mcz)
|
|
Thank you!
Yes.
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.
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 |
Re: The Inbox: Kernel-cmfcmf.1251.mcz
|
|
In reply to this post by Chris Muller-3
Hi Chris, I think we mean the same here. I just wanted to add the word "meaningful" to your suggestions: "Answer whether the receiver can be sent a message named aSymbol and expect a meaningful answer." Best, Marcel
|
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |