Ask HN: Honest question, comments above or under code?
I write mine above.
2 comments
In general, above the class, function, or method, but if details are needed for individual bits then at the end of the line or below (doesn't happen often).
However, a lot of commentary goes into tests rather than the code, and there I prefer to use doctests, a literate style that interleaves prose and code. In general, it follows this pattern: tell them what you're going to do (ie. prose), do it (code), explain what just happened (prose), and prove it did what you say (test code). Doctests are mostly integration/functional tests rather than unit tests.
However, a lot of commentary goes into tests rather than the code, and there I prefer to use doctests, a literate style that interleaves prose and code. In general, it follows this pattern: tell them what you're going to do (ie. prose), do it (code), explain what just happened (prose), and prove it did what you say (test code). Doctests are mostly integration/functional tests rather than unit tests.
Examples usually have it above.