Hi again Jaromir,

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:

____
ObjectWithDocumentation - an abstract superclass for objects that allows
maintenance of an authoring stamp, a body of documentation, and a
properties dictionary.
____

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.

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.

 - Chris

On Fri, Jun 3, 2022 at 10:27 AM Jaromir Matas <mail at jaromir.net> wrote:

> Hi Marcel,
>
> 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 :)
>
> Thanks,
>
> Jaromir
>
>
>
> *From: *Marcel Taeumel <marcel.taeumel at hpi.de>
> *Sent: *Friday, June 3, 2022 17:01
> *To: *squeak-dev <squeak-dev at lists.squeakfoundation.org>
> *Subject: *Re: [squeak-dev] Note sharing inside Squeak?
>
>
>
> Hi Karl --
>
>
>
> > But we still don't have good documentation.
>
>
>
> 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:
>
>
>
> - Commentary in the method
>
> - Extra commentary method
>
> - Class comment
>
> - Help topic
>
>
>
> All these places can be found with Squeak's image-wide text search.
>
>
>
> Best,
>
> Marcel
>
> Am 02.06.2022 22:42:54 schrieb karl ramberg <karlramberg at gmail.com>:
>
> This story is repeated so often. But we still don't have good
> documentation.
>
> Or what we have is not very accessible.
>
> I remember struggling quite a bit before grasping the Squeak/ Smalltalk
> way of working.
>
> 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.
>
>
>
> Best,
>
> Karl
>
>
>
> On Thu, Jun 2, 2022 at 9:16 PM Jaromir Matas <mail at jaromir.net> wrote:
>
> Hi Chris, Marcel, Tim, John, all:
>
>
>
> Thanks very much for all your thoughts. There seem to be a few distinct
> "types" of comments:
>
> - "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
>
> - "one liner" comments sprinkled around the code to help reading the code
> (Chris's examples, not to be overused)
>
> - "documentation" comments with detailed imlementation or other info
> (desirable but swamping the method and forcing one to scroll...)
>
> - plus surely some not so distinct
>
>
>
> I have a suggestion:
>
>
>
> 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)
>
>
>
> 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)
>
>
>
> Thanks again,
>
> Jaromir
>
>
>
> --
>
> *Jaromír Matas*
>
> mail at jaromir.net
>
>
>
> *From: *Jaromir Matas <mail at jaromir.net>
> *Sent: *Wednesday, June 1, 2022 20:07
> *To: *ma.chris.m at gmail.com; The general-purpose Squeak developers list
> <squeak-dev at lists.squeakfoundation.org>
> *Subject: *Re: [squeak-dev] Note sharing inside Squeak?
>
>
>
> Hi Chris,
>
>
>
> > 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.
>
>
>
> 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?)
>
>
>
> > 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.
>
>
>
> 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.
>
>
>
> > 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.
>
>
>
> 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.
>
>
>
> > 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".
>
> > [...]
>
> > I'm dubious, though, that this would be a good practice in Smalltalk
> code except in rare circumstances.
>
>
>
> 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.
>
>
>
> Thanks for your comments!
>
> best,
>
> Jaromir
>
>
>
> --
>
> *Jaromír Matas*
>
> mail at jaromir.net
>
>
>
> *From: *Chris Muller <asqueaker at gmail.com>
> *Sent: *Tuesday, May 31, 2022 23:02
> *To: *The general-purpose Squeak developers list
> <squeak-dev at lists.squeakfoundation.org>
> *Subject: *Re: [squeak-dev] Note sharing inside Squeak?
>
>
>
> Hi Jaromir,
>
>
>
> 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 *code* (developers).  Also, that first comment
> (the UI comment) could even, for example, identify the argument types and
> return type in some standard *syntax*, that might even be processable --
> although that might be handled better with a pragma.
>
>
>
> 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.
>
>
>
> *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.
>
>
>
> Best,
>
>   Chris
>
>
>
> On Sun, May 29, 2022 at 2:56 PM Jaromir Matas <mail at jaromir.net> wrote:
>
> Hi all,
>
> 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…
>
> Any suggestion welcome :)
>
> Best,
>
> Jaromir
>
>
>
> --
>
> *Jaromír Matas*
>
> mail at jaromir.net
>
>
>
>
>
>
>
>
>
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220603/e8e92f2b/attachment.html>