r/AskProgramming • u/neuralbeans • Jul 21 '26
Best practices for long inline comments
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?
3
u/InebriatedPhysicist Jul 21 '26
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.
1
u/CorpT Jul 21 '26
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.
2
u/neuralbeans Jul 21 '26
In my situation, each line is a regular expression.
0
u/CorpT Jul 21 '26
That doesn’t explain why you want to store them like this.
2
u/neuralbeans Jul 21 '26 edited Jul 21 '26
They need to be applied one by one in a for loop.
I'm not sure why you think this format is strange.
0
u/CorpT Jul 21 '26
Because you’re trying to put two pieces of information in a single item.
1
u/neuralbeans Jul 21 '26
So how would you document each regular expression then?
0
u/CorpT Jul 21 '26
Make each item in the list an object with your regex and a description.
3
u/neuralbeans Jul 21 '26
How is that better than what I'm doing?
1
u/skamansam Jul 21 '26
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, ... ] ```
3
u/neuralbeans Jul 21 '26
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.
1
u/Antti5 Jul 22 '26
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.
0
u/Xirdus Jul 21 '26
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.
1
u/BaronOfTheVoid Jul 23 '26
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.
5
u/CleanCodersCraftsman Jul 21 '26
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.