Compiler-cmm.480 is rooted in the idea that the format of comments is a
human communication that fundamentally belongs to the author.  I _really_
think Compiler-mt.480 is the wrong approach if the goal is aesthetically
"pleasing" comments.  I put that in quotes because it's your personal
preference -- I myself very much dislike long comments to be
indented because it prioritizes aesthetics over readability.  When a
comment is long enough to take more than one line, it's worth seeing its
delineation of that section of code in the left margin.

If you prefer them to be indented, please make a Shout preference that
dynamically formats comments into indented paragraphs.  That solution
ensures *every* width is a good width instead of trying to guess about it
and, IMO, intruding terribly into the sovereignty of someone's hand-crafted
comments because someone else prefers indentation.  Plus, an arbitrary
width makes comments even *harder* to whenever the width you're reading in
is narrower than the arbitrary width decided by the formatter (see
screenshot, I picked a random method).

[image: formatting-code-good-comment-bad.png]

Squeak can do so much better, *easily* even, Text has supported indentation
for years and years!

Best,
  Chris

On Wed, Jul 20, 2022 at 2:50 AM Marcel Taeumel <marcel.taeumel at hpi.de>
wrote:

> Hi all -
>
> See Compiler-mt.480 (Inbox) for an alternative solution.
>
> Best,
> Marcel
>
> Am 20.07.2022 09:36:46 schrieb Marcel Taeumel <marcel.taeumel at hpi.de>:
> Hi Nicolas --
>
> > [...] 75 em means that we'll get at least 75 chars...
>
> Typography-wise, it just gets a little bit more complicated
> with non-monospaced fonts. For a prosa comment in Squeak's
> default proportional font, 75 em or 75 characters-per-line might
> be much on screen considering English text.
>
> At the moment, we have preferences to play around with this:
> PluggableTextMorph softLineWrapAtVisualWrapBorder
> PluggableTextMorph visualWrapBorder
> PluggableTextMorph visualWrapBorderLimit
>
> 80 characters seem to be common for mono-spaced fonts.
> On average, that value also seems to work with Squeak's
> proportional Bitstream Vera Sans. It's a compromise. Tool
> windows are not a sheet of real paper.
>
> Best,
> Marcel
>
> Am 19.07.2022 22:19:32 schrieb Nicolas Cellier <
> nicolas.cellier.aka.nice at gmail.com>:
> Hi all,
> em is a typical unit used in latex. Since it's the largest latin letter in
> most fonts, 75 em means that we'll get at least 75 chars...
> Nicolas
>
> Le mar. 19 juil. 2022 à 14:50, Marcel Taeumel <marcel.taeumel at hpi.de> a
> écrit :
>
>> > I thought that the em would actually be a unit to get
>> > something like x characters in width, using M as the
>> > particular character as a basis.
>>
>> Ah, right. Should work. Yet, I would not write a new
>> text composition algorithm but re-use our existing one.
>> And that one is based on either "type factor " or
>> "num chars".
>>
>> Best,
>> Marcel
>>
>> Am 19.07.2022 14:37:40 schrieb Jakob Reschke <jakres+squeak at gmail.com>:
>> If the research has already been done, then there is no need for guessing
>> and further suggestions. All the better :-)
>>
>> I thought that the em would actually be a unit to get something like x
>> characters in width, using M as the particular character as a basis.
>>
>>
>>
>>
>> Am Di., 19. Juli 2022 um 14:21 Uhr schrieb Marcel Taeumel <
>> marcel.taeumel at hpi.de>:
>>
>>> > 75em may also be a good limit, now that Number even understands such a
>>> selector.
>>>
>>> Nope. We need something independent from a scale factor and thus the
>>> default font size as pretty-printed format can be checked in. Better use
>>> "66 characters", not 75em. No rendering/font properties. For multi-line
>>> comments, use the line-break algorithm as in Text >> #withNoLineLongerThan:.
>>>
>>> Please read the commentary in
>>> TextStyle >> #compositionWidthForNumChars
>>>
>>> Best,
>>> Marcel
>>>
>>> Am 14.07.2022 19:55:04 schrieb tim Rowledge <tim at rowledge.org>:
>>>
>>>
>>> > On 2022-07-14, at 10:48 AM, Jakob Reschke wrote:
>>> >
>>> > 75em may also be a good limit, now that Number even understands such a
>>> selector.
>>> > https://baymard.com/blog/line-length-readability
>>>
>>> That's an excellent point; extra-long lines are really annoying to read
>>> in general.
>>>
>>> >
>>> > But seeing Tim's examples: before we start tweaking the indentation of
>>> comments by the pretty printer, which would have it insert tabs or spaces
>>> or anything else, better implement that proposal to display comment lines
>>> left-aligned with the opening ", without requiring indentation characters
>>> in the source text. Remember that other thread about whether or not to have
>>> line breaks in comments? Somebody posted a screenshot from Dolphin
>>> Smalltalk that shows what I am referring to.
>>> >
>>> > To leave the comments untouched by the pretty-printer seems reasonable
>>> to me for now.
>>>
>>> Oh, I'm not wanting to have any tabs or spaces inserted - I want the
>>> formatting to be live and use the left indent. Shout does all that work to
>>> colour (etc) the text so why not use the fact that it detects comments.
>>>
>>>
>>> tim
>>> --
>>> tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
>>> Useful random insult:- His seat back is not in the full upright and
>>> locked position.
>>>
>>>
>>>
>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220721/55a62f9b/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: formatting-code-good-comment-bad.png
Type: image/png
Size: 84489 bytes
Desc: not available
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220721/55a62f9b/attachment-0001.png>