[squeak-dev] Manual line breaks in code

Jaromir Matas mail at jaromir.net
Sat Apr 2 13:20:06 UTC 2022


Hi Christoph,

> do I understand correctly that only think in Squeak's text composition you are missing are hanging indents?

Yes, take a look at Dolphin’s simple solution in the enclosed screenshots; the second picture shows what Dolphin does when you resize the window: it simply indents the comment based on the indentation of the line the comment starts on… Actually, it analogically indents the code lines as well so the result looks neat and consistent.

Best,


--

Jaromír Matas

+420 777 492 777
mail at jaromir.net

From: christoph.thiede at student.hpi.uni-potsdam.de<mailto:christoph.thiede at student.hpi.uni-potsdam.de>
Sent: Friday, April 1, 2022 23:42
To: squeak-dev at lists.squeakfoundation.org<mailto:squeak-dev at lists.squeakfoundation.org>
Subject: Re: [squeak-dev] Manual line breaks in code

Hi Jaromir,

do I understand correctly that only think in Squeak's text composition you are missing are hanging indents? I can't imagine that it should be overly complicated to implement them. But this might be a matter of taste - especially in code with many indentations, I am happy that to exploit the full width of the viewport for longer comments.

> > My proposal is to not include the documentation in a comment at all.
>
> I?m not sure how to understand that; I?ve recently worked on a few methods (#terminate etc.) where I felt the need to add as much comment text as possible? even more comment than code :) Would that be considered a ?documentation?? Where else to put it?

I think Lauren was just referring to the representation of the method comment via a separate textbox. However, for myself, this would not be simple & minimalistic enough, I guess. ?

Best,
Christoph

---
Sent from Squeak Inbox Talk<https://github.com/hpi-swa-lab/squeak-inbox-talk>

On 2022-04-01T20:30:33+00:00, mail at jaromir.net wrote:

> Hi Christoph, Tobias, Lauren, all
>
> > A comment like this is totally fine to me:
>
> terminate
> "Stop the receiver forever.
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks) on the stack, even if they are currently in progress. If already active unwind contexts should not be continued, send #terminateAggressively instead.
> NOTE THAT bla bla bla!"
>
> I dare to disagree here ? this looks distracting to me. Dolphin solved this by indenting long lines to make them into a tidy indented paragraph.
>
> > But not this:
>
> terminate
> "Stop the receiver forever.
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks)
> on the stack, even if they are currently in progress. If
> already active unwind contexts should not be continued,
> send #terminateAggressively instead.
> NOTE THAT bla bla bla!"
>
> Unless Squeak somehow employs a reasonable indentation I personally prefer this way ? especially for comments inside the indented code ? long lines break indentation and the resulting look is unfortunate; I?m trying to avoid long comments but sometimes a longer comment just feels appropriate.
>
> > I put linebreaks there because I want them exactly there :)
>
> Yes, I do that too? to manually enforce indentation, really.
>
> I?ve noticed VW are struggling with the same dilemma too :)
>
> > My proposal is to not include the documentation in a comment at all.
>
> I?m not sure how to understand that; I?ve recently worked on a few methods (#terminate etc.) where I felt the need to add as much comment text as possible? even more comment than code :) Would that be considered a ?documentation?? Where else to put it?
>
> Thanks,
>
> --
>
> Jaromír Matas
>
> mail at jaromir.net
>
> From: christoph.thiede at student.hpi.uni-potsdam.de<mailto:christoph.thiede at student.hpi.uni-potsdam.de>
> Sent: Friday, April 1, 2022 18:35
> To: squeak-dev at lists.squeakfoundation.org<mailto:squeak-dev at lists.squeakfoundation.org>
> Subject: Re: [squeak-dev] Manual line breaks in code
>
> Hi Tobias, Hi Lauren,
>
> > I put linebreaks there because I want them exactly there :)
>
> But then you are talking more about paragraphs rather than linebreaks, aren't you? :-)
>
> A comment like this is totally fine to me:
>
> terminate
> "Stop the receiver forever.
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks) on the stack, even if they are currently in progress. If already active unwind contexts should not be continued, send #terminateAggressively instead.
> NOTE THAT bla bla bla!"
>
> But not this:
>
> terminate
> "Stop the receiver forever.
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks)
> on the stack, even if they are currently in progress. If
> already active unwind contexts should not be continued,
> send #terminateAggressively instead.
> NOTE THAT bla bla bla!"
>
> In the second example, we would just stupidically do the work of the text composer. Similar to the "tabs vs spaces" debate, spaces/manual linebreaks prescribe the appearance of the code/text, whereas tabs/automatic line-breaking leave this decision to the tooling of the reader or author. If I resize my browser window, I would like its contents to be re-layouted as flexibly as possible.
>
> Even worse, manual linebreaks blur the differences between semantically distinct paragraphs and composition-specific linebreaks.
>
> @Lauren:
>
> > My proposal is to not include the documentation in a comment at all.
>
> I think you are neglecting comments in the midst of any method, which occur pretty frequently in Squeak and are an important part of Smalltalk programming IMHO. :)
>
> Best,
> Christoph
>
> ---
> Sent from Squeak Inbox Talk<https://github.com/hpi-swa-lab/squeak-inbox-talk>
>
> On 2022-04-01T16:06:01+00:00, drurowin at gmail.com wrote:
>
> > Hi Christoph, Marcel, Tobias,
> >
> > My proposal is to not include the documentation in a comment at all.
> >
> > Add a dedicated text box to the browser for the comment and treat method
> > comments like class comments, but then display both code and
> > documentation simultaneously side by side. Then there could be
> > completely different rules for formatting text from formatting code. I
> > want each text line to be narrow... but I want each code line to be able
> > to be wide to take advantage of indentation.
> >
> > On 4/1/22 11:42, christoph.thiede at student.hpi.uni-potsdam.de wrote:
> > >> How about email's format=flowed?
> > >
> > > A problem with this could be that some systems do not preserve trailing spaces. For instance, they do not appear in the mailing list archive. :-)
> > Unrelated, I checked my copy of the sent mail and it looks like my
> > client stripped the trailing spaces when it got sent to prepare it for
> > the ml archive.
> >
> > This might be a problem with the inlined diffs that get sent out when
> > people save new versions, but I still think it's the least intrusive
> > option and doesn't require any special non-space-bar spaces. It
> > wouldn't affect code samples in the comments, and you could detect
> > paragraphs all on one literal line by the period-return-return and
> > period-endOfComment patterns.
> >
> > If you press return you get a normal line break (for people like Tobias
> > and myself, who put in line breaks because they're supposed to be
> > there), and if you hit the space bar right before that it signals the
> > comment formatting engine to use the user's preference to change the
> > line widths.
> >
> >
>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220401/e8949a81/attachment.html>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220402/8dc72923/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot 2022-04-02 150643.png
Type: image/png
Size: 34728 bytes
Desc: Screenshot 2022-04-02 150643.png
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220402/8dc72923/attachment.png>


More information about the Squeak-dev mailing list