Hi Jaromir,<br>
<br>
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.<br>
<br>
> > My proposal is to not include the documentation in a comment at all.<br>
> <br>
> 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?<br>
<br>
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. ?<br>
<br>
Best,<br>
Christoph<br>
<br>
<font color="#808080">---<br>
</font><font color="#808080"><i>Sent from </i></font><font color="#808080"><i><a href="https://github.com/hpi-swa-lab/squeak-inbox-talk"><u><font color="#808080">Squeak Inbox Talk</font></u></a></i></font><br>
<br>
On 2022-04-01T20:30:33+00:00, mail@jaromir.net wrote:<br>
<br>
> Hi Christoph, Tobias, Lauren, all<br>
> <br>
> > A comment like this is totally fine to me:<br>
> <br>
> terminate<br>
> "Stop the receiver forever.<br>
> 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.<br>
> NOTE THAT bla bla bla!"<br>
> <br>
> 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.<br>
> <br>
> > But not this:<br>
> <br>
> terminate<br>
> "Stop the receiver forever.<br>
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks)<br>
> on the stack, even if they are currently in progress. If<br>
> already active unwind contexts should not be continued,<br>
> send #terminateAggressively instead.<br>
> NOTE THAT bla bla bla!"<br>
> <br>
> 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.<br>
> <br>
> > I put linebreaks there because I want them exactly there :)<br>
> <br>
> Yes, I do that too? to manually enforce indentation, really.<br>
> <br>
> I?ve noticed VW are struggling with the same dilemma too :)<br>
> <br>
> > My proposal is to not include the documentation in a comment at all.<br>
> <br>
> 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?<br>
> <br>
> Thanks,<br>
> <br>
> --<br>
> <br>
> Jaromír Matas<br>
> <br>
> mail at jaromir.net<br>
> <br>
> From: christoph.thiede at student.hpi.uni-potsdam.de<mailto:christoph.thiede at student.hpi.uni-potsdam.de><br>
> Sent: Friday, April 1, 2022 18:35<br>
> To: squeak-dev at lists.squeakfoundation.org<mailto:squeak-dev at lists.squeakfoundation.org><br>
> Subject: Re: [squeak-dev] Manual line breaks in code<br>
> <br>
> Hi Tobias, Hi Lauren,<br>
> <br>
> > I put linebreaks there because I want them exactly there :)<br>
> <br>
> But then you are talking more about paragraphs rather than linebreaks, aren't you? :-)<br>
> <br>
> A comment like this is totally fine to me:<br>
> <br>
> terminate<br>
> "Stop the receiver forever.<br>
> 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.<br>
> NOTE THAT bla bla bla!"<br>
> <br>
> But not this:<br>
> <br>
> terminate<br>
> "Stop the receiver forever.<br>
> Run all unwind contexts (#ensure:/#ifCurtailed: blocks)<br>
> on the stack, even if they are currently in progress. If<br>
> already active unwind contexts should not be continued,<br>
> send #terminateAggressively instead.<br>
> NOTE THAT bla bla bla!"<br>
> <br>
> 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.<br>
> <br>
> Even worse, manual linebreaks blur the differences between semantically distinct paragraphs and composition-specific linebreaks.<br>
> <br>
> @Lauren:<br>
> <br>
> > My proposal is to not include the documentation in a comment at all.<br>
> <br>
> 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. :)<br>
> <br>
> Best,<br>
> Christoph<br>
> <br>
> ---<br>
> Sent from Squeak Inbox Talk<https://github.com/hpi-swa-lab/squeak-inbox-talk><br>
> <br>
> On 2022-04-01T16:06:01+00:00, drurowin at gmail.com wrote:<br>
> <br>
> > Hi Christoph, Marcel, Tobias,<br>
> ><br>
> > My proposal is to not include the documentation in a comment at all.<br>
> ><br>
> > Add a dedicated text box to the browser for the comment and treat method<br>
> > comments like class comments, but then display both code and<br>
> > documentation simultaneously side by side. Then there could be<br>
> > completely different rules for formatting text from formatting code. I<br>
> > want each text line to be narrow... but I want each code line to be able<br>
> > to be wide to take advantage of indentation.<br>
> ><br>
> > On 4/1/22 11:42, christoph.thiede at student.hpi.uni-potsdam.de wrote:<br>
> > >> How about email's format=flowed?<br>
> > ><br>
> > > 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. :-)<br>
> > Unrelated, I checked my copy of the sent mail and it looks like my<br>
> > client stripped the trailing spaces when it got sent to prepare it for<br>
> > the ml archive.<br>
> ><br>
> > This might be a problem with the inlined diffs that get sent out when<br>
> > people save new versions, but I still think it's the least intrusive<br>
> > option and doesn't require any special non-space-bar spaces. It<br>
> > wouldn't affect code samples in the comments, and you could detect<br>
> > paragraphs all on one literal line by the period-return-return and<br>
> > period-endOfComment patterns.<br>
> ><br>
> > If you press return you get a normal line break (for people like Tobias<br>
> > and myself, who put in line breaks because they're supposed to be<br>
> > there), and if you hit the space bar right before that it signals the<br>
> > comment formatting engine to use the user's preference to change the<br>
> > line widths.<br>
> ><br>
> ><br>
> <br>
> -------------- next part --------------<br>
> An HTML attachment was scrubbed...<br>
> URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220401/e8949a81/attachment.html><br>
> <br>
>