<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"Calibri Light";
panose-1:2 15 3 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
p.MsoNoSpacing, li.MsoNoSpacing, div.MsoNoSpacing
{mso-style-priority:1;
margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
.MsoChpDefault
{mso-style-type:export-only;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="#954F72" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal">Hi Christoph, Tobias, Lauren, all</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> A comment like this is totally fine to me:<br>
<br>
<b>terminate</b><span style="color:black"> <br>
</span> <span style="color:black"> </span><span style="color:teal">"Stop the receiver forever.<br>
</span> <span style="color:teal"> 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>
</span> <span style="color:teal"> NOTE THAT bla bla bla!"</span><br>
<br>
</p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> But not this:<br>
<br>
<b>terminate</b><span style="color:black"> <br>
</span> <span style="color:black"> </span><span style="color:teal">"Stop the receiver forever.<br>
</span> <span style="color:teal"> 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>
</span> <span style="color:teal"> NOTE THAT bla bla bla!"</span><br>
<br>
</p>
<p class="MsoNormal">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.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> I put linebreaks there because I want them exactly there :)<br>
<br>
</p>
<p class="MsoNormal">Yes, I do that too… to manually enforce indentation, really.</p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I’ve noticed VW are struggling with the same dilemma too :) </p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> My proposal is to not include the documentation in a comment at all.<br>
<br>
</p>
<p class="MsoNormal">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? </p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Thanks,</p>
<p class="MsoNoSpacing"><span lang="CS">--</span></p>
<p class="MsoNoSpacing"><strong><span style="font-family:"Calibri Light",sans-serif;color:#333333;font-weight:normal">Jaromír Matas</span></strong><span style="font-family:"Calibri Light",sans-serif;color:#555555"><o:p></o:p></span></p>
<p class="MsoNoSpacing"><span style="font-family:"Calibri Light",sans-serif;color:#2E75B6">mail@jaromir.net</span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div style="mso-element:para-border-div;border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="border:none;padding:0in"><b>From: </b><a href="mailto:christoph.thiede@student.hpi.uni-potsdam.de">christoph.thiede@student.hpi.uni-potsdam.de</a><br>
<b>Sent: </b>Friday, April 1, 2022 18:35<br>
<b>To: </b><a href="mailto:squeak-dev@lists.squeakfoundation.org">squeak-dev@lists.squeakfoundation.org</a><br>
<b>Subject: </b>Re: [squeak-dev] Manual line breaks in code</p>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">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>
<b>terminate</b><span style="color:black"> <br>
</span> <span style="color:black"> </span><span style="color:teal">"Stop the receiver forever.<br>
</span> <span style="color:teal"> 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>
</span> <span style="color:teal"> NOTE THAT bla bla bla!"</span><br>
<br>
But not this:<br>
<br>
<b>terminate</b><span style="color:black"> <br>
</span> <span style="color:black"> </span><span style="color:teal">"Stop the receiver forever.<br>
</span> <span style="color:teal"> 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>
</span> <span style="color:teal"> NOTE THAT bla bla bla!"</span><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>
<span style="color:gray">---<br>
<i>Sent from </i></span><a href="https://github.com/hpi-swa-lab/squeak-inbox-talk"><i><span style="color:gray">Squeak Inbox Talk</span></i></a><br>
<br>
On 2022-04-01T16:06:01+00:00, drurowin@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>
> <o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</body>
</html>