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 :).
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).
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 :)
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.
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.
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.
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.
9 comments
[ 2.1 ms ] story [ 29.2 ms ] thread