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@jaromir.net
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas mail@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@jaromir.net
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO: 1) creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors) 2) only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
--
Jaromír Matas
mail@jaromir.net
From: John-Reed Maffeomailto:jrmaffeo@gmail.com Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers listmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas <mail@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
-- John-Reed Maffeo
My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas mail@jaromir.net wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas mail@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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best, Marcel Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org: My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how. Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumelmailto:marcel.taeumel@hpi.de Sent: Monday, May 30, 2022 11:31 To: squeak-devmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best, Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org: My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense. SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net: Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how. Thanks! -- Jaromír Matas mail@jaromir.net From: Marcel Taeumel [mailto:marcel.taeumel@hpi.de] Sent: Monday, May 30, 2022 11:31 To: squeak-dev [mailto:squeak-dev@lists.squeakfoundation.org] Subject: Re: [squeak-dev] Note sharing inside Squeak? Hi Jaromir -- You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-) I would rather not remove such information too far from the method itself. Best, Marcel Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org: My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
Hi Marcel,
Sounds good; I'll give it a try to squeeze some more stuff into comments unless it gets too bloated :)
Thanks again
From: Marcel Taeumelmailto:marcel.taeumel@hpi.de Sent: Monday, May 30, 2022 13:16 To: squeak-devmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense. SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net: Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how. Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumelmailto:marcel.taeumel@hpi.de Sent: Monday, May 30, 2022 11:31 To: squeak-devmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best, Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org: My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
Hi Jaromir --
Please document what you think is worth documenting. We can always move documentation if we find a better place.
Be clear and concise for the sake of understanding, not because of technical limitations.
Best, Marcel Am 30.05.2022 13:31:36 schrieb Jaromir Matas mail@jaromir.net: Hi Marcel, Sounds good; I'll give it a try to squeeze some more stuff into comments unless it gets too bloated :) Thanks again From: Marcel Taeumel [mailto:marcel.taeumel@hpi.de] Sent: Monday, May 30, 2022 13:16 To: squeak-dev [mailto:squeak-dev@lists.squeakfoundation.org] Subject: Re: [squeak-dev] Note sharing inside Squeak? Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions. SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense. SqueakLicenseHelp openHelpBrowser model showFirstTopic. That's as convenient as it gets for now. :-) Best, Marcel Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net: Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how. Thanks! -- Jaromír Matas mail@jaromir.net From: Marcel Taeumel [mailto:marcel.taeumel@hpi.de] Sent: Monday, May 30, 2022 11:31 To: squeak-dev [mailto:squeak-dev@lists.squeakfoundation.org] Subject: Re: [squeak-dev] Note sharing inside Squeak? Hi Jaromir -- You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-) I would rather not remove such information too far from the method itself. Best, Marcel Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org: My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
cmd-6 (ctl-6 on windows I think) opens a little dialog
with those 'Link' options. If we added a 'Link to Help' it would become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with instructions on the heel.
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledgemailto:tim@rowledge.org Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers listmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
[cid:F0D75AE1-8E6B-463D-B392-653B47D4205C]
with those 'Link' options. If we added a 'Link to Help' it would become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel <marcel.taeumel@hpi.demailto:marcel.taeumel@hpi.de> wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas <mail@jaromir.netmailto:mail@jaromir.net>:
Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.netmailto:mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim -- tim Rowledge; tim@rowledge.orgmailto:tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with instructions on the heel.
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas mail@jaromir.net wrote:
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
<Screen Shot 2022-05-30 at 10.35.44 AM.png>
with those 'Link' options. If we added a 'Link to Help' it would become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with instructions on the heel.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim No single raindrop believes it is to blame for the flood
Ctrl-5 or 6 brings up the DockingBar menus. Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Excerpts from Help menu/ Keyboard shortcuts that can't be used on windows:
Text Emphasis (not available on all platforms) Cmd-1 type the first method argument Cmd-2 type the second method argument Cmd-3 type the third method argument Cmd-4 type the fourth method argument Cmd-5 color, action-on-click, link to class comment, link to method, url, custom attributes (brings up a menu) Cmd-6 italic Cmd-7 bold Cmd-8 struck-out Cmd-9 underlined Cmd-0 make plain (removes all attributes)
Best, Karl
On Mon, May 30, 2022 at 8:52 PM tim Rowledge tim@rowledge.org wrote:
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas mail@jaromir.net wrote:
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
<Screen Shot 2022-05-30 at 10.35.44 AM.png>
with those 'Link' options. If we added a 'Link to Help' it would become
very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that
information is located.
For example, if you created a new help topic, just write "For more
information, see
the Help Browser and the topic X." No need to get too fancy with text
actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method
itself.
Exactly my concern. If it was in a help somewhere there would have to be
a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method.
There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method
itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be method
comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing.
If the comments are too long for the top of the method it doesn't hurt
to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments
but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive
(too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want
to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a
comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+
years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text
itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with
instructions on the heel.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim No single raindrop believes it is to blame for the flood
On 2022-05-30, at 12:14 PM, karl ramberg karlramberg@gmail.com wrote:
Ctrl-5 or 6 brings up the DockingBar menus. Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Try alt?
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Asking whether machines can think is like asking whether submarines can swim.
Hi,
On Windows, I can access the dialog with Alt+5 both in a workspace and in a system browser. With Ctrl+5 I get to the docking bar menus, too. If the preferences work as they used to, one can probably swap the Ctrl and Alt behaviors.
Kind regards, Jakob
Am Mo., 30. Mai 2022 um 21:14 Uhr schrieb karl ramberg < karlramberg@gmail.com>:
Ctrl-5 or 6 brings up the DockingBar menus. Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Excerpts from Help menu/ Keyboard shortcuts that can't be used on windows:
Text Emphasis (not available on all platforms) Cmd-1 type the first method argument Cmd-2 type the second method argument Cmd-3 type the third method argument Cmd-4 type the fourth method argument Cmd-5 color, action-on-click, link to class comment, link to method, url, custom attributes (brings up a menu) Cmd-6 italic Cmd-7 bold Cmd-8 struck-out Cmd-9 underlined Cmd-0 make plain (removes all attributes)
Best, Karl
On Mon, May 30, 2022 at 8:52 PM tim Rowledge tim@rowledge.org wrote:
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas mail@jaromir.net wrote:
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
<Screen Shot 2022-05-30 at 10.35.44 AM.png>
with those 'Link' options. If we added a 'Link to Help' it would become
very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de
wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that
information is located.
For example, if you created a new help topic, just write "For more
information, see
the Help Browser and the topic X." No need to get too fancy with text
actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method
itself.
Exactly my concern. If it was in a help somewhere there would have to
be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method.
There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method
itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be
method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing.
If the comments are too long for the top of the method it doesn't hurt
to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use
comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be
counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want
to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a
comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after
30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text
itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with
instructions on the heel.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim No single raindrop believes it is to blame for the flood
Thanks for feedback. It works with alt+5. I thought I tested with alt, but it turns out I tested on a weird keyboard where there is another key between alt and the space bar. Facepalm
Uploaded update to help text to the inbox
Best, Karl
On Mon, May 30, 2022 at 11:22 PM Jakob Reschke jakres+squeak@gmail.com wrote:
Hi,
On Windows, I can access the dialog with Alt+5 both in a workspace and in a system browser. With Ctrl+5 I get to the docking bar menus, too. If the preferences work as they used to, one can probably swap the Ctrl and Alt behaviors.
Kind regards, Jakob
Am Mo., 30. Mai 2022 um 21:14 Uhr schrieb karl ramberg < karlramberg@gmail.com>:
Ctrl-5 or 6 brings up the DockingBar menus. Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Excerpts from Help menu/ Keyboard shortcuts that can't be used on windows:
Text Emphasis (not available on all platforms) Cmd-1 type the first method argument Cmd-2 type the second method argument Cmd-3 type the third method argument Cmd-4 type the fourth method argument Cmd-5 color, action-on-click, link to class comment, link to method, url, custom attributes (brings up a menu) Cmd-6 italic Cmd-7 bold Cmd-8 struck-out Cmd-9 underlined Cmd-0 make plain (removes all attributes)
Best, Karl
On Mon, May 30, 2022 at 8:52 PM tim Rowledge tim@rowledge.org wrote:
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas mail@jaromir.net wrote:
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
<Screen Shot 2022-05-30 at 10.35.44 AM.png>
with those 'Link' options. If we added a 'Link to Help' it would
become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de
wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that
information is located.
For example, if you created a new help topic, just write "For more
information, see
the Help Browser and the topic X." No need to get too fancy with text
actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method
itself.
Exactly my concern. If it was in a help somewhere there would have to
be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method.
There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method
itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be
method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing.
If the comments are too long for the top of the method it doesn't hurt
to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use
comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be
counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want
to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a
comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after
30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text
itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with
instructions on the heel.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim No single raindrop believes it is to blame for the flood
Hi Jakob --
If the preferences work as they used to, one can probably swap the Ctrl and Alt behaviors.
This has always been a misconception. Please read KeyboardEvent >> #checkCommandKey. Those old preferences are gone for good. The new ones are called "Map ... to ..." where each preference explains what's going on.
In this case, the world-main docking bar is that greedy and will always catch CTRL+5, even if other code would be able to interpret the same event by checking #commandKeyPressed, which would answer "true" if, for example, "Map CONTROL keys to COMMAND keys" is enabled ... which is by default on Windows and Linux systems.
Best, Marcel Am 30.05.2022 23:22:39 schrieb Jakob Reschke jakres+squeak@gmail.com: Hi,
On Windows, I can access the dialog with Alt+5 both in a workspace and in a system browser. With Ctrl+5 I get to the docking bar menus, too.
If the preferences work as they used to, one can probably swap the Ctrl and Alt behaviors.
Kind regards, Jakob
Am Mo., 30. Mai 2022 um 21:14 Uhr schrieb karl ramberg <karlramberg@gmail.com [mailto:karlramberg@gmail.com]>:
Ctrl-5 or 6 brings up the DockingBar menus.
Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Excerpts from Help menu/ Keyboard shortcuts that can't be used on windows:
Text Emphasis (not available on all platforms) Cmd-1 type the first method argument Cmd-2 type the second method argument Cmd-3 type the third method argument Cmd-4 type the fourth method argument Cmd-5 color, action-on-click, link to class comment, link to method, url, custom attributes (brings up a menu) Cmd-6 italic Cmd-7 bold Cmd-8 struck-out Cmd-9 underlined Cmd-0 make plain (removes all attributes)
Best, Karl
On Mon, May 30, 2022 at 8:52 PM tim Rowledge <tim@rowledge.org [mailto:tim@rowledge.org]> wrote:
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas <mail@jaromir.net [mailto:mail@jaromir.net]> wrote:
I can’t figure out how you got the menu - from where? Thanks :) From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak? cmd-6 (ctl-6 on windows I think) opens a little dialog <Screen Shot 2022-05-30 at 10.35.44 AM.png> with those 'Link' options. If we added a 'Link to Help' it would become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel <marcel.taeumel@hpi.de [mailto:marcel.taeumel@hpi.de]> wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that information is located. For example, if you created a new help topic, just write "For more information, see the Help Browser and the topic X." No need to get too fancy with text actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas <mail@jaromir.net [mailto:mail@jaromir.net]>:
Hi Marcel,
I would rather not remove such information too far from the method itself.
Exactly my concern. If it was in a help somewhere there would have to be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net [mailto:mail@jaromir.net]
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method. There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge <tim@rowledge.org [mailto:tim@rowledge.org]>:
My suggestion is that notes about details of the method should be method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing. If the comments are too long for the top of the method it doesn't hurt to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net [mailto:mail@jaromir.net]
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after 30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net [mailto:mail@jaromir.net]
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org [mailto:tim@rowledge.org]; http://www.rowledge.org/tim [http://www.rowledge.org/tim] Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org [mailto:tim@rowledge.org]; http://www.rowledge.org/tim [http://www.rowledge.org/tim] Useful random insult:- Couldn't pour water out of a boot with instructions on the heel.
tim -- tim Rowledge; tim@rowledge.org [mailto:tim@rowledge.org]; http://www.rowledge.org/tim [http://www.rowledge.org/tim] No single raindrop believes it is to blame for the flood
Ok, so it is not obvious how this linking works.
Write *<Point Comment>* including < and > and select it. Then press Alt + 5 and select "link to comment of class"
Best, Karl
On Tue, May 31, 2022 at 2:35 PM Marcel Taeumel marcel.taeumel@hpi.de wrote:
Hi Jakob --
If the preferences work as they used to, one can probably swap the Ctrl
and Alt behaviors.
This has always been a misconception. Please read KeyboardEvent >> #checkCommandKey. Those old preferences are gone for good. The new ones are called "Map ... to ..." where each preference explains what's going on.
In this case, the world-main docking bar is that greedy and will always catch CTRL+5, even if other code would be able to interpret the same event by checking #commandKeyPressed, which would answer "true" if, for example, "Map CONTROL keys to COMMAND keys" is enabled ... which is by default on Windows and Linux systems.
Best, Marcel
Am 30.05.2022 23:22:39 schrieb Jakob Reschke jakres+squeak@gmail.com: Hi,
On Windows, I can access the dialog with Alt+5 both in a workspace and in a system browser. With Ctrl+5 I get to the docking bar menus, too. If the preferences work as they used to, one can probably swap the Ctrl and Alt behaviors.
Kind regards, Jakob
Am Mo., 30. Mai 2022 um 21:14 Uhr schrieb karl ramberg < karlramberg@gmail.com>:
Ctrl-5 or 6 brings up the DockingBar menus. Sadly I don't think the text emphasis menu is possible to reach on Windows :-(
Excerpts from Help menu/ Keyboard shortcuts that can't be used on windows:
Text Emphasis (not available on all platforms) Cmd-1 type the first method argument Cmd-2 type the second method argument Cmd-3 type the third method argument Cmd-4 type the fourth method argument Cmd-5 color, action-on-click, link to class comment, link to method, url, custom attributes (brings up a menu) Cmd-6 italic Cmd-7 bold Cmd-8 struck-out Cmd-9 underlined Cmd-0 make plain (removes all attributes)
Best, Karl
On Mon, May 30, 2022 at 8:52 PM tim Rowledge tim@rowledge.org wrote:
It's that -
cmd-6 (ctl-6 on windows I think) opens a little dialog
that does it. As long as you are focussed in a text morph.
On 2022-05-30, at 11:36 AM, Jaromir Matas mail@jaromir.net wrote:
I can’t figure out how you got the menu - from where? Thanks :)
From: tim Rowledge Sent: Monday, May 30, 2022 19:37 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
cmd-6 (ctl-6 on windows I think) opens a little dialog
<Screen Shot 2022-05-30 at 10.35.44 AM.png>
with those 'Link' options. If we added a 'Link to Help' it would
become very easy to connect a few words in a method/code comment to a more expansive explanation in the Help browser.
On 2022-05-30, at 4:15 AM, Marcel Taeumel marcel.taeumel@hpi.de
wrote:
Hi Jaromir --
but I don’t even know if such linking to a help is possible and how.
Don't forget that you can always explain to the user where that
information is located.
For example, if you created a new help topic, just write "For more
information, see
the Help Browser and the topic X." No need to get too fancy with text
actions.
SqueakLicenseHelp openHelpBrowser model showTopicNamed: #officialLicense.
SqueakLicenseHelp openHelpBrowser model showFirstTopic.
That's as convenient as it gets for now. :-)
Best, Marcel
Am 30.05.2022 12:43:58 schrieb Jaromir Matas mail@jaromir.net:
Hi Marcel,
I would rather not remove such information too far from the method
itself.
Exactly my concern. If it was in a help somewhere there would have to
be a link included in the method… but I don’t even know if such linking to a help is possible and how.
Thanks!
--
Jaromír Matas
mail@jaromir.net
From: Marcel Taeumel Sent: Monday, May 30, 2022 11:31 To: squeak-dev Subject: Re: [squeak-dev] Note sharing inside Squeak?
Hi Jaromir --
You can also append another longer comment to the end of that method.
There are examples of this in the image. Somewhere. :-)
I would rather not remove such information too far from the method
itself.
Best,
Marcel
Am 30.05.2022 02:33:37 schrieb tim Rowledge tim@rowledge.org:
My suggestion is that notes about details of the method should be
method comments until they get really long. If that happens I would expect that quite a few related methods might have need of extensive commentary too and in that case it would be smart to add a help page to explain the whole thing.
If the comments are too long for the top of the method it doesn't hurt
to have more at the bottom.
On 2022-05-29, at 3:38 PM, Jaromir Matas wrote:
John, Thanks for your reply. It was my initial idea to possibly use
comments but there’s few issues with that approach IMO:
- creating a version for each comment change may be
counterproductive (too many versions, the method authorship - it’s better to have fewer versions with easily identifiable authors)
- only core developers could update trunk comments; I wouldn’t want
to place that burden on anybody
But yeah, maybe I could try to put some more stuff and examples as a
comment after the code. But a more informal but easily reachable place would still be nice.
Best, Jaromir
-- Jaromír Matas mail@jaromir.net
From: John-Reed Maffeo Sent: Monday, May 30, 2022 0:04 To: The general-purpose Squeak developers list Subject: Re: [squeak-dev] Note sharing inside Squeak?
jaromir,
Who said comments should be terse and polished?
It would be more helpful to people like myself (still a nube after
30+ years) to see a long, complex entry into a method's comment than no comment at all! Putting comments in some other place is counter productive in my mind.
Why not put a usage example into comments or the body of the text
itself?
- jrm
On Sun, May 29, 2022 at 12:56 PM Jaromir Matas 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@jaromir.net
-- John-Reed Maffeo
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Common sense – so rare it’s a goddam superpower
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Useful random insult:- Couldn't pour water out of a boot with
instructions on the heel.
tim
tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim No single raindrop believes it is to blame for the flood
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@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@jaromir.net
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@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
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@jaromir.net
From: Jaromir Matasmailto:mail@jaromir.net Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com; The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
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@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@jaromir.net
*From: *Jaromir Matas mail@jaromir.net *Sent: *Wednesday, June 1, 2022 20:07 *To: *ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@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@jaromir.net
*From: *Chris Muller asqueaker@gmail.com *Sent: *Tuesday, May 31, 2022 23:02 *To: *The general-purpose Squeak developers list squeak-dev@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@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@jaromir.net
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@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@jaromir.net [mailto:mail@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@jaromir.net [mailto:mail@jaromir.net] From: Jaromir Matas [mailto:mail@jaromir.net] Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.com [mailto:ma.chris.m@gmail.com]; The general-purpose Squeak developers list [mailto:squeak-dev@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@jaromir.net [mailto:mail@jaromir.net] From: Chris Muller [mailto:asqueaker@gmail.com] Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers list [mailto:squeak-dev@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@jaromir.net [mailto:mail@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@jaromir.net [mailto:mail@jaromir.net]
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 Taeumelmailto:marcel.taeumel@hpi.de Sent: Friday, June 3, 2022 17:01 To: squeak-devmailto:squeak-dev@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@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
From: Jaromir Matasmailto:mail@jaromir.net Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com; The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
Hi Jaromir --
Take a look at the classes SqueakHelp and SqueakProjectHelp. Try to create your own CustomHelp in that fashion. You can edit those topics directly in the HelpBrowser.
Best, Marcel Am 03.06.2022 17:27:05 schrieb Jaromir Matas mail@jaromir.net: 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 [mailto:marcel.taeumel@hpi.de] Sent: Friday, June 3, 2022 17:01 To: squeak-dev [mailto:squeak-dev@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@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@jaromir.net [mailto:mail@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@jaromir.net [mailto:mail@jaromir.net] From: Jaromir Matas [mailto:mail@jaromir.net] Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.com [mailto:ma.chris.m@gmail.com]; The general-purpose Squeak developers list [mailto:squeak-dev@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@jaromir.net [mailto:mail@jaromir.net] From: Chris Muller [mailto:asqueaker@gmail.com] Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers list [mailto:squeak-dev@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@jaromir.net [mailto:mail@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@jaromir.net [mailto:mail@jaromir.net]
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@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@hpi.de *Sent: *Friday, June 3, 2022 17:01 *To: *squeak-dev squeak-dev@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@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@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@jaromir.net
*From: *Jaromir Matas mail@jaromir.net *Sent: *Wednesday, June 1, 2022 20:07 *To: *ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@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@jaromir.net
*From: *Chris Muller asqueaker@gmail.com *Sent: *Tuesday, May 31, 2022 23:02 *To: *The general-purpose Squeak developers list squeak-dev@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@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@jaromir.net
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@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@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@hpi.de *Sent: *Friday, June 3, 2022 17:01 *To: *squeak-dev squeak-dev@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@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@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@jaromir.net
*From: *Jaromir Matas mail@jaromir.net *Sent: *Wednesday, June 1, 2022 20:07 *To: *ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@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@jaromir.net
*From: *Chris Muller asqueaker@gmail.com *Sent: *Tuesday, May 31, 2022 23:02 *To: *The general-purpose Squeak developers list squeak-dev@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@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@jaromir.net
Hi Karl, Yes, such links in comments would be great; the link in your example points to the same place as when you right-click a class and select ‘browse documentation’: it’s a collection of all first comments from every method. Such info doesn’t seem to me very useful but if the link opened a more detailed info about a method – that would be exactly it – and accessible via a similar link that you provided.
Btw, when you place the link inside the Browser and click on it, the Help window will open *behind* the browser window… probably a bug somewhere (not in your changeset, I mean).
I’m going to take a look at the class ObjectWithDocumentation Chris suggested; however after a quick glance I have no idea where to start, what the class is supposed to do, what the entry points are etc – I haven’t noticed any documentation ??
Thanks for your input! Best,
--
Jaromír Matas
mail@jaromir.net
________________________________ From: Squeak-dev squeak-dev-bounces@lists.squeakfoundation.org on behalf of karl ramberg karlramberg@gmail.com Sent: Saturday, June 4, 2022 6:55:13 PM To: ma.chris.m@gmail.com ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
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@gmail.commailto:asqueaker@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@jaromir.netmailto:mail@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 Taeumelmailto:marcel.taeumel@hpi.de Sent: Friday, June 3, 2022 17:01 To: squeak-devmailto:squeak-dev@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@gmail.commailto:karlramberg@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
From: Jaromir Matasmailto:mail@jaromir.net Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com; The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
On Tue, Jun 7, 2022 at 9:58 PM Jaromir Matas mail@jaromir.net wrote:
Hi Karl,
Yes, such links in comments would be great; the link in your example points to the same place as when you right-click a class and select ‘browse documentation’: it’s a collection of all first comments from every method. Such info doesn’t seem to me very useful but if the link opened a more detailed info about a method – that would be exactly it – and accessible via a similar link that you provided.
For this to be useful you must really create a help topic and link to that. See Marcel's mail above about creating help topics.
Btw, when you place the link inside the Browser and click on it, the Help window will open **behind** the browser window… probably a bug somewhere (not in your changeset, I mean).
That seems like a bug to me also. Not sure where. Maybe in tool builder somewhere.
Best, Karl
I’m going to take a look at the class ObjectWithDocumentation Chris suggested; however after a quick glance I have no idea where to start, what the class is supposed to do, what the entry points are etc – I haven’t noticed any documentation 😃
Thanks for your input!
Best,
--
*Jaromír Matas*
mail@jaromir.net
*From:* Squeak-dev squeak-dev-bounces@lists.squeakfoundation.org on behalf of karl ramberg karlramberg@gmail.com *Sent:* Saturday, June 4, 2022 6:55:13 PM *To:* ma.chris.m@gmail.com ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org *Subject:* Re: [squeak-dev] Note sharing inside Squeak?
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@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@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@hpi.de *Sent: *Friday, June 3, 2022 17:01 *To: *squeak-dev squeak-dev@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@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@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@jaromir.net
*From: *Jaromir Matas mail@jaromir.net *Sent: *Wednesday, June 1, 2022 20:07 *To: *ma.chris.m@gmail.com; The general-purpose Squeak developers list squeak-dev@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@jaromir.net
*From: *Chris Muller asqueaker@gmail.com *Sent: *Tuesday, May 31, 2022 23:02 *To: *The general-purpose Squeak developers list squeak-dev@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@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@jaromir.net
Hi Karl,
For this to be useful you must really create a help topic and link to that.
See Marcel's mail above about creating help topics.
Yes, I’m already checking it out :)
--
Jaromír Matas
mail@jaromir.net
From: karl rambergmailto:karlramberg@gmail.com Sent: Wednesday, June 8, 2022 12:47 To: The general-purpose Squeak developers listmailto:squeak-dev@lists.squeakfoundation.org Subject: Re: [squeak-dev] Note sharing inside Squeak?
On Tue, Jun 7, 2022 at 9:58 PM Jaromir Matas <mail@jaromir.netmailto:mail@jaromir.net> wrote: Hi Karl, Yes, such links in comments would be great; the link in your example points to the same place as when you right-click a class and select ‘browse documentation’: it’s a collection of all first comments from every method. Such info doesn’t seem to me very useful but if the link opened a more detailed info about a method – that would be exactly it – and accessible via a similar link that you provided.
For this to be useful you must really create a help topic and link to that. See Marcel's mail above about creating help topics.
Btw, when you place the link inside the Browser and click on it, the Help window will open *behind* the browser window… probably a bug somewhere (not in your changeset, I mean).
That seems like a bug to me also. Not sure where. Maybe in tool builder somewhere.
Best, Karl
I’m going to take a look at the class ObjectWithDocumentation Chris suggested; however after a quick glance I have no idea where to start, what the class is supposed to do, what the entry points are etc – I haven’t noticed any documentation 😃
Thanks for your input! Best,
--
Jaromír Matas
mail@jaromir.netmailto:mail@jaromir.net
From: Squeak-dev <squeak-dev-bounces@lists.squeakfoundation.orgmailto:squeak-dev-bounces@lists.squeakfoundation.org> on behalf of karl ramberg <karlramberg@gmail.commailto:karlramberg@gmail.com> Sent: Saturday, June 4, 2022 6:55:13 PM To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com <ma.chris.m@gmail.commailto:ma.chris.m@gmail.com>; The general-purpose Squeak developers list <squeak-dev@lists.squeakfoundation.orgmailto:squeak-dev@lists.squeakfoundation.org> Subject: Re: [squeak-dev] Note sharing inside Squeak?
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@gmail.commailto:asqueaker@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@jaromir.netmailto:mail@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 Taeumelmailto:marcel.taeumel@hpi.de Sent: Friday, June 3, 2022 17:01 To: squeak-devmailto:squeak-dev@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@gmail.commailto:karlramberg@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
From: Jaromir Matasmailto:mail@jaromir.net Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com; The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
Hi Marcel, all
A quick question: I’m trying to put together a line-by-line description of #terminate; would it be helpful to integrate the text as a class side commentary method now, before I manage to learn & create proper Help topics later this year? I’m enclosing what I have at the moment fyi (language corrections still needed).
Many thanks, jaromir
From: Marcel Taeumelmailto:marcel.taeumel@hpi.de Sent: Friday, June 3, 2022 17:01 To: squeak-devmailto:squeak-dev@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@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
From: Jaromir Matasmailto:mail@jaromir.net Sent: Wednesday, June 1, 2022 20:07 To: ma.chris.m@gmail.commailto:ma.chris.m@gmail.com; The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@jaromir.net
From: Chris Mullermailto:asqueaker@gmail.com Sent: Tuesday, May 31, 2022 23:02 To: The general-purpose Squeak developers listmailto:squeak-dev@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@jaromir.netmailto:mail@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@jaromir.netmailto:mail@jaromir.net
Hi Jaromir,
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".
For example, I picked a method at random in the image and rewrote it in his style: ____ detectMin: aBlock "Evaluate aBlock with each of the receiver's elements as the argument. Answer the element for which aBlock evaluates to the lowest number. If collection empty, return nil."
| minElement minValue | * "enumerate my elements"* self do: [:each | | val | *"has a current minimum already been established?"* minValue ifNotNil: [ *"yes, does the current element compute less?"* (val := aBlock value: each) < minValue ifTrue: [ *"yes, assign the new minimum"* minElement := each. minValue := val ] ] ifNil: [ *"no. Establish current as the minimum"* minElement := each. minValue := aBlock value: each ] ]. * "Answer the element that computed the minimum value."* ^ minElement ____
This was in Java, which doesn't read as well, so I actually found his technique helpful when reading his code. I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.
- Chris
On Sun, May 29, 2022 at 2:56 PM Jaromir Matas mail@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@jaromir.net
One issue I have with lots of inline comments like here is that it makes it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
Best, Karl
On Wed, Jun 1, 2022 at 4:49 AM Chris Muller asqueaker@gmail.com wrote:
Hi Jaromir,
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".
For example, I picked a method at random in the image and rewrote it in his style: ____ detectMin: aBlock "Evaluate aBlock with each of the receiver's elements as the argument. Answer the element for which aBlock evaluates to the lowest number. If collection empty, return nil."
| minElement minValue | * "enumerate my elements"* self do: [:each | | val | *"has a current minimum already been established?"* minValue ifNotNil: [ *"yes, does the current element compute less?"* (val := aBlock value: each) < minValue ifTrue: [ *"yes, assign the new minimum"* minElement := each. minValue := val ] ] ifNil: [ *"no. Establish current as the minimum"* minElement := each. minValue := aBlock value: each ] ].
"Answer the element that computed the minimum value."*
This was in Java, which doesn't read as well, so I actually found his technique helpful when reading his code. I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.
- Chris
On Sun, May 29, 2022 at 2:56 PM Jaromir Matas mail@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@jaromir.net
On Mon, Jun 27, 2022 at 10:44 AM karl ramberg karlramberg@gmail.com wrote:
One issue I have with lots of inline comments like here is that it makes it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
If I was going to hack a solution to this I'd implement the following on " enclose/remove. On enclose replace matching pairs of "'s with `` (two back ticks) & '' (two forward ticks). On remove, replace matching pairs of `` & '' with pairs of "s.
Best,
Karl
On Wed, Jun 1, 2022 at 4:49 AM Chris Muller asqueaker@gmail.com wrote:
Hi Jaromir,
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".
For example, I picked a method at random in the image and rewrote it in his style: ____ detectMin: aBlock "Evaluate aBlock with each of the receiver's elements as the argument. Answer the element for which aBlock evaluates to the lowest number. If collection empty, return nil."
| minElement minValue | * "enumerate my elements"* self do: [:each | | val | *"has a current minimum already been established?"* minValue ifNotNil: [ *"yes, does the current element computeless?"* (val := aBlock value: each) < minValue ifTrue: [ *"yes, assign the new minimum"* minElement := each. minValue := val ] ] ifNil: [ *"no. Establish current as the minimum"* minElement := each. minValue := aBlock value: each ] ].
"Answer the element that computed the minimum value."*
This was in Java, which doesn't read as well, so I actually found his technique helpful when reading his code. I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.
- Chris
On Sun, May 29, 2022 at 2:56 PM Jaromir Matas mail@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@jaromir.net
On Mon, Jun 27, 2022 at 2:35 PM Eliot Miranda eliot.miranda@gmail.com wrote:
On Mon, Jun 27, 2022 at 10:44 AM karl ramberg karlramberg@gmail.com wrote:
One issue I have with lots of inline comments like here is that it makes it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
If I was going to hack a solution to this I'd implement the following on " enclose/remove. On enclose replace matching pairs of "'s with `` (two back ticks) & '' (two forward ticks). On remove, replace matching pairs of `` & '' with pairs of "s.
In the SmalltalkEditor only.
Best,
Karl
On Wed, Jun 1, 2022 at 4:49 AM Chris Muller asqueaker@gmail.com wrote:
Hi Jaromir,
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".
For example, I picked a method at random in the image and rewrote it in his style: ____ detectMin: aBlock "Evaluate aBlock with each of the receiver's elements as the argument. Answer the element for which aBlock evaluates to the lowest number. If collection empty, return nil."
| minElement minValue | * "enumerate my elements"* self do: [:each | | val | *"has a current minimum already been established?"* minValue ifNotNil: [ *"yes, does the current element computeless?"* (val := aBlock value: each) < minValue ifTrue: [ *"yes, assign the new minimum"* minElement := each. minValue := val ] ] ifNil: [ *"no. Establish current as the minimum"* minElement := each. minValue := aBlock value: each ] ].
"Answer the element that computed the minimum value."*
This was in Java, which doesn't read as well, so I actually found his technique helpful when reading his code. I'm dubious, though, that this would be a good practice in Smalltalk code except in rare circumstances.
- Chris
On Sun, May 29, 2022 at 2:56 PM Jaromir Matas mail@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@jaromir.net
-- _,,,^..^,,,_ best, Eliot
One issue I have with lots of inline comments like here is that it makes it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
What I sometimes do is just enclose a chunk of code within a block. It has the nice effect that comments inside the block are not a problem.
With Chris example:
| minElement minValue | "enumerate my elements" self do: [:each | | val | "has a current minimum already been established?" minValue ifNotNil: [ "yes, does the current element compute less?" (val := aBlock value: each) < minValue ifTrue: [ "yes, assign the new minimum" minElement := each. minValue := val ] ] ifNil: [ "no. Establish current as the minimum" minElement := each. minValue := aBlock value: each ] ]. "Answer the element that computed the minimum value." ^ minElement
I would do for example something like
| minElement minValue | "enumerate my elements" self do: [:each | | val | "has a current minimum already been established?" minValue ifNotNil: [ "yes, does the current element compute less?" [ (val := aBlock value: each) < minValue ifTrue: [ "yes, assign the new minimum" minElement := each. minValue := val ] ].
val := 0 "for testing"]
ifNil: [ "no. Establish current as the minimum" minElement := each. minValue := aBlock value: each ] ]. "Answer the element that computed the minimum value." ^ minElement
Stef
On Tue, Jun 28, 2022 at 4:17 AM Stéphane Rollandin lecteur@zogotounga.net wrote:
One issue I have with lots of inline comments like here is that it makes it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
What I sometimes do is just enclose a chunk of code within a block. It has the nice effect that comments inside the block are not a problem.
That's what I do as well, and this method provides the advantage that "senders" will still find that code.
- Chris
Thanks for the tip about using blocks. I'll keep that in mind next time I debug issues. :-D
Best, Karl
On Wed, Jun 29, 2022 at 8:52 PM Chris Muller asqueaker@gmail.com wrote:
On Tue, Jun 28, 2022 at 4:17 AM Stéphane Rollandin lecteur@zogotounga.net wrote:
One issue I have with lots of inline comments like here is that it
makes
it really painful if you want to comment out a section of the code for debugging, testing etc. A way of skipping whole lines like C style // single line comment could maybe help with that.
What I sometimes do is just enclose a chunk of code within a block. It has the nice effect that comments inside the block are not a problem.
That's what I do as well, and this method provides the advantage that "senders" will still find that code.
- Chris
squeak-dev@lists.squeakfoundation.org
-
Chris Muller -
Eliot Miranda -
Jakob Reschke -
Jaromir Matas -
John-Reed Maffeo -
karl ramberg -
Marcel Taeumel -
Stéphane Rollandin -
tim Rowledge