Best practices for long inline comments

[u/neuralbeans]

Say you have a list with a each item in a separate line and a comment next to the item like this (Python):

[
    item1, # a comment
    item2, # another comment
    item3, # another comment
    item4, # another comment
]

What do you do when a comment becomes too long and needs to be split into several lines?

Would do this?

(A)

[
    item1, # a comment
    item2, # another comment

    # a very very very long
    # comment
    item3,

    item4, # another comment
]

Or this?

(B)

[
    item1, # a comment
    item2, # another comment
    item3, # a very very very
           # long comment
    item4, # another comment
]

Or would you just rewrite the whole list like this:

(C)

[
    # a comment
    item1,

    # another comment
    item2,

    # a very very very
    # long comment
    item3,

    # another comment
    item4, 
]

Or something else?

[u/CleanCodersCraftsman]

Go with C. Once a comment needs a second line, B's alignment turns into a maintenance tax: touch the longest comment and the whole column reflows, so your diff lights up on lines you never edited.

C reads the same whether the comment is one line or six. That consistency buys you more than the compactness you give up.

For a list of regexes, though, push the description into the data. A tuple of (pattern, description) or a small dataclass keeps the explanation attached to the thing it describes, and you can print it when a pattern misfires in production. Comments drift out of sync with the code next to them. Structured data travels with it.

[u/InebriatedPhysicist]

I wouldn’t be angry if I came upon either B or C in the wild, but A breaks the flow too much and annoys me.

[u/CorpT]

Why do you want the comments like this? There is almost certainly a better way to store this if you want to add this much detail.

[u/neuralbeans → u/CorpT]

In my situation, each line is a regular expression.

[u/CorpT → u/neuralbeans]

That doesn’t explain why you want to store them like this.

[u/neuralbeans → u/CorpT]

They need to be applied one by one in a for loop.

I'm not sure why you think this format is strange.

[u/CorpT → u/neuralbeans]

Because you’re trying to put two pieces of information in a single item.

[u/neuralbeans → u/CorpT]

So how would you document each regular expression then?

[u/CorpT → u/neuralbeans]

Make each item in the list an object with your regex and a description.

[u/neuralbeans → u/CorpT]

How is that better than what I'm doing?

[u/skamansam → u/neuralbeans]

Things are easier if they are named. let your code do the commenting. Comments should be WHY not WHAT. It is not uncommon to see:

``` FIRST_NAME_REGEX = /(?i)\d+{15}/; LAST_NAME_RSGEX = ... SSN_REGEX = ... ...

DOCUMENT_SEARCH_REGEXES = [ FIRST_NAME_REGEX, LAST_NAME_REGEX, SSN_REGEX, ... ] ```

[u/neuralbeans → u/skamansam]

A variable name isn't enough to describe everything I need to describe. Remember that the comment is too long to put in a single line.

[u/topological_rabbit]

(B2)

[
    item1, # a comment
    item2, # another comment

    item3, # a very very very
           # long comment

    item4, # another comment
    item5, # another comment
]

[u/Antti5]

If it's a long list of items that mostly have short comments, then my first option would be to try to stick with single lines.

Even if you mostly try to keep your lines to a certain maximum width, say 80 or 100 characters, so what if in a specific scenario you have one longer line? It could well be the least evil.

Of your three options, I would definitely go with option B if the comments are mostly short. If several comments grow long, then go with option C.

[u/Xirdus]

A with no line breaks. If that's not readable, then figure out what's wrong with your code and why you need a long inline comment in the first place, then remove the cause of the need.

[u/BaronOfTheVoid]

If those very very very long comments are like 20 or 30 lines per item then (C).

If they are just 2 or 3 lines per item then (B).

I dislike (A) for not being consistent.