Style: line length and wrapping of comments in JavaScript [closed]

Question

I'm fine with staying under 80 characters per line for code (even if some consider that limit outdated), but I'm split (no pun intended) when it comes to splitting comments over multiple lines, versus writing them on one line (as long as it needs to be) and letting the editors taking care of the wrapping.

I think comments merit a separate discussion given their text (rather than code) nature, with different readability considerations, and a paragraph (rather than line) orientation.

After reading the discussion on comment styles, I've narrowed down my important development flow aspects to the following:

• Using an editor that doesn't support wrapping isn't a problem or excuse. I'm the primary maintainer of the code, with very occasional contributions via GitHub. emacs or vi won't be used.
• The code being published on GitHub, should facilitate editing with their editor, which does support soft wraps:
• I get to pick the style, so there's no adherence to an existing style.

Arbitrary line lengths - pros

• searches won't fail just because two consecutive words you happened to search for were arbitrarily separated by \n *
• excellent screen real estate utilization

Arbitrary line lengths - cons

• with soft wrapping, looks weird in JSDoc:
• really minor, but GitHub's diff mode is "Unified" by default, which displays a horizontal scrollbar. However, if you click "Split", GitHub's diff soft wraps:
• GitHub's viewer does NOT support wrapping, and its width is 128 characters (though some "GitHub wide" user styles exist).

Limited line length pros:

• text is read fastest at 50-75 chars/line, but we're not writing a novel here and if you read the comments, you can afford to spend a few extra seconds
• better display in legacy tools that don't support wrapping

Limited line length cons:

• inserting text in the beginning of a comment while hard wrapping each of its lines can easily cause a cascade of false diffs:

In the wild, I've seen mostly hard wraps (limited line length), despite the diff issue above being rather common and jarring.

What am I missing and how can I make a decision?

Why aren't arbitrarily long lines more commonly encountered in contemporary projects?

Answer 1

It looks like you did an in-depth analysis of your situation, your contextual factor being mostly GitHub.

In other projects, the contextual factor is the IDE being used, with three situations being most used:

• 80-characters limit. This is an great choice for developers using emacs/vi, or those who blindly follow some style conventions (an interesting point is that jslint's maxlen default value is unlimited).

  The benefit here is consistency. The proper plugins for the text editors help as well: you type, and the editor deals with line endings to enforce the 80-characters limit. As simple as that.

  Note that, although the limit of 80 is popular, other numbers can be used as well, and this is usually not a problem; it just sometimes requires custom configuration.

• No limit. This is a great choice for those who made the effort configuring word-wrap in their IDE. If Mary uses her Visual Studio on a 24-inch monitor, while Jeff works on a 19-inch laptop, it might me that the actual number of characters per line for Jeff would be much less than for Mary. But it doesn't matter, since Visual Studio will display exactly as much characters as possible, going to a new line when needed.

  The benefit here is that nobody cares about the actual IDE/configuration used by other developers. The text displays neatly for everyone, and everyone is happy. Until, once, the team hires a developer who loves emacs or vi, and until the team starts using a tool which can't deal with word-wrap.

• “This works on my machine” limit. Developers who use IDEs where the size of the window can change and who haven't configured word-wrap are sometimes inclined to insert line breaks where it looks nice. They type text in their 173-characters window, and when reaching the character 171, they do a line break to start a new word on a new line.

  This is a wrong approach:

  1. Such text looks ugly as soon as the window is resized. Make it 168-characters long, and you get either a vertical scroll (ewwww!) or word-wrap which looks like this:

     //                                       The arbitrary line end is here ↴
     //                                        The new word-wrap is here ↴   ┊
     ····if·(this.windowActive·&&·this.findStartupTimer().isExpired)↵    ┊   ┊
     ····{↵                                                              ┊   ┊
     ········console.log('Entering·the·primary·loop.');↵                 ┊   ┊
     ········//·TODO:·implement·the·primary·loop·which·will·handle·the·▖ ┊   ┊
     events↵                                                             ┊   ┊
     ········//·from·the·application.↵                                   ┊   ┊
     ····}↵                                                              ┊   ┊
     

     ^{The developer decided to insert a line break after “events” to make the text look nice in the context of the original line end. As soon as the window width is slightly reduced, the word-wrap capable IDE introduces a new line after “handle the,” making “events” appear alone on a line. That's not particularly readable.}

     It doesn't accommodate well larger screens either. It would be bearable if everyone used a consistent limit: I would waste space on the right, but so does this page on softwareengineering.SE, where two thirds of the space on my monitor is simply blank. The problem, however, is the lack of consistency. It's like if a question on this site would use 1000 pixels width, while an answer would prefer a 800 pixels width, and then some comment would span to 1 200 pixels, and so on.

  2. Few tools can accommodate a “Hey, a line break here looks nice” rule. You can't enforce it automatically on commit. You can't ask your IDE to insert line breaks for you.

Unfortunately, in some communities, having “This works on my machine” limit is quite popular. Corporate C# code is full of those nasty line breaks, because Visual Studio made a wrong decision to disable word-wrap by default, and most programmers don't know how to enable it. Don't be one of them.

When it comes to choosing between a strict, consistent limit and no limit at all, make a choice depending on the tools you use. It seems that in your case, the choice would be the lack of limit.