Maintaning multiline comments in the Scala editor is unnecessarily hard

[Ben Hutchison]

Recently I have been spending a bit of time /maintaining/ multi-line
comments in Scala source. By maintaining I mean updating and rewriting
comment text to keep it relevant as the code changes, including moving
text around via cut-n-paste. Not only does the current tooling lack
even simple assistance for this important activity (comments &
Scaladoc are only useful if it's maintained!), it has features which
actively obstruct comment maintenance.

As comments are maintained, text is added or moves around and line
lengths change. There is no Reformat for Scala comments in a file to
ensure they are a consistent width, eg max 120 chars. That feature
would be tremendously useful for comment maintenance.

Similarly, when entering comments the first time, it would be nice to
have auto-wrap at a (eg 120) wrap threshold, rather than manually
inserting newlines.

Further, the tradition of prefixing every comment line with a *
(inherited from Java, which inherited it from C/C++) works to obstruct
maintenance, because if you move lines around, you end up with *
symbols mixed through the text. In these days of syntax highlighting
(even on github source browse), how important is a * to distinguish
comments?

Infuriatingly, the Scala editor seemingly insists on prefixing every
line of a comment with a *, and offers no option to disable this
unwanted feature (that actually /harms/ long-term maintainability).

I suspect this unhappy feature set was inherited from Eclipse's Java
editor. In total, they encourage a "write-once" approach to comments &
Scaladocs, which detracts from their ongoing usefulness and accuracy.

-Ben

[iulian dragos]

Hi Ben,

On Sat, Jun 16, 2012 at 5:36 AM, Ben Hutchison <brhut...@gmail.com> wrote:
> As comments are maintained, text is added or moves around and line
> lengths change. There is no Reformat for Scala comments in a file to
> ensure they are a consistent width, eg max 120 chars. That feature
> would be tremendously useful for comment maintenance.

You raise a very good point. We're using Scalariform for formatting,
and there is a related issue:

https://github.com/mdr/scalariform/issues/4

Matt commented that it's not easy to fix. Maybe if more people demand
the feature, he'll implement it.

> Similarly, when entering comments the first time, it would be nice to
> have auto-wrap at a (eg 120) wrap threshold, rather than manually
> inserting newlines.
>
> Further, the tradition  of prefixing every comment line with a *
> (inherited from Java, which inherited it from C/C++) works to obstruct
> maintenance, because if you move lines around, you end up with *
> symbols mixed through the text. In these days of syntax highlighting
> (even on github source browse), how important is a * to distinguish
> comments?
>
> Infuriatingly, the Scala editor seemingly insists on prefixing every
> line of a comment with a *, and offers no option to disable this
> unwanted feature (that actually /harms/ long-term maintainability).
>
> I suspect this unhappy feature set was inherited from Eclipse's Java
> editor.

Indeed.

> In total, they encourage a "write-once" approach to comments &
> Scaladocs, which detracts from their ongoing usefulness and accuracy.
>
> -Ben

--
« Je déteste la montagne, ça cache le paysage »
Alphonse Allais

[Matt Russell]

On Tuesday, June 19, 2012 4:17:03 PM UTC+1, Iulian Dragos wrote:

You raise a very good point. We're using Scalariform for formatting,
and there is a related issue:

https://github.com/mdr/scalariform/issues/4

Matt commented that it's not easy to fix. Maybe if more people demand
the feature, he'll implement it.

 

Maybe this is a case of perfect is the enemy of good -- for now, I can add a word-wrap routine to break at whitespace. Later we can do fancy-pants Scaladoc aware wrapping.

 -- Matt

[noncom]

This is not so critical for me, but sometimes I get into similar textual ASCII adventure games where I have to wade through extra spaces, collect stars and align every line of a text so that it fits in width. Although it is funny, I would like to be delivered from this. You say it is hard to implement, so ok, but I hope that some day in the future, when there are not so many other critical tasks, it will come. I just wanted to say that I upvote the original post)