

Ask HN: Do you prefer in-line comments for documenting code? - usermac

Just curious. I like comments that are on the same line as the code and wondered if others felt the same.
======
markbnj
I like vertical white space in code, and so I usually use blocked comments
right above the relevant code. I think the side-by-side style has gotten less
and less practical as languages have become more expressive and lines have
become longer (also due to much more screen space). Just a working theory
though :).

------
WorldMaker
I realized in a discussion thread on Literate Programming styles that majority
of my comments nowadays have moved into the source control commits. Then you
somewhat get the best of inline comments in your source control annotated view
of the code, including that the comments truly only stay attached for as long
as they stay relevant (walking backwards in time as necessary to see the
history of that line).

------
Spoom
I'll generally docblock methods, and use full line comments if something in
the method needs a little more explanation on why it's doing what it does. I
don't often use mid-line comments; mostly those are if I'm temporarily
omitting something, and then that gets deleted before being committed.

------
daxfohl
Only sometimes, specifically when you can do a "complex" transform in one line
and breaking it into multiple lines doesn't really make it much easier to
understand. Recent example: `.map(x->x%2==0?-x:x) //negate all even numbers`.
Otherwise, no.

------
veddox
I rarely put comments on the same line as my code, usually that makes the line
too long (I try to stay in the 80 char margin). If I want to specifically
annotate that one line, I'll insert a comment line right above it.

------
MalcolmDiggs
I prefer for comments to be given their own line/block above whatever they're
referencing. No real reason behind this preference, it's just what I like :)

------
lsiebert
I like them for notes to myself for like toy projects, but I hate reading them
for other people. Being able to scan down the page and see comments is
helpful.

------
debacle
The last few places I've worked have had rules against code and comments on
the same line. I think it's a good rule.

------
usermac
Askr here. I brought it up because, well, it makes it easier to move the
comment with the code.

