[squeak-dev] Note sharing inside Squeak?

karl ramberg karlramberg at gmail.com
Sat Jun 4 16:55:13 UTC 2022


Here is small change set that make links that open a HelpBrowser on a class.
Preferably the class is a help topic like TerseGuideHelp

Example:
TerseGuideHelp Help
Select text, press Alt+5 (CMD on Mac) and select 'Link to help on class'

Best,
Karl

On Sat, Jun 4, 2022 at 3:36 AM Chris Muller <asqueaker at gmail.com> wrote:

> 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/20220604/3dc70a31/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: LinkToHelpBrowser.3.cs
Type: application/octet-stream
Size: 4015 bytes
Desc: not available
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220604/3dc70a31/attachment.obj>


More information about the Squeak-dev mailing list