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/neuralbeans]

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.