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>