These are standard typographical practices. I do set my comment color to super light so comments don't distract me too much when reading code, but I wish there was a better way.
It helps if the inline commentary is differently colored or in a separate box.
I also use light colors for comments when reading source code, but I personally prefer this over having them as footnotes or sidenotes.
Programming should move out the typographical stone age into something a bit more modern.
In the article, I'm assuming the left column takes up a bit less space on the author's browser viewport, but it takes up about 45% of mine, while a bit of the code trails off the page.
The reason I think it works so well with physical books is that the dimensions are known and not user-configurable, so it's easier to guarantee that the sidenotes look appropriate. With free-form comments that could range from a one-line comment to large paragraphs to explain one line of code, I don't think there's a way to make sure they would look reasonable in all cases. (I could be wrong)
A good example of easy-to-read in-text notes (in my opinion) are those in Fred Hebert's LYSE [1]. They could be sidenotes or footnotes, but instead they're in-text, which makes them easier for me to read in a browser, regardless of screen size, but also pretty easy to skip over since they're color-coded and in their own box.
I think it's more of a medium difference than a book-typography-is-more-modern one. When scrolling through a web page or code, I mostly find the single-column in-text notes/comments easier to use, though I see why some people might prefer sidenotes.
[1] http://learnyousomeerlang.com/starting-out-for-real#bool-and...
It is like parenthetical statements in prose: you can't really make them disappear, they are right their in your face. It is considered bad style if they aren't extremely brief, otherwise you should use a foot or side note.
class Widget
{
/**
* @access public
* The name of the widget
*/
public $name;
/**
* @access private
* The widget's material composition
*/
private $composition;
// ... yada, yada ...
}
Even with syntax highlighting on, it can be a pain in the ass to see the code through all that comment noise. I guess I should take the time to configure my folding more.No. I prefer them at the bottom (that's why they're called footnote) and with a tooltip for convenience.
I don't see how that relates to the idiotic idea of scattering comments/code over two wide columns.
Making my eyes jump horizontally across the page every few lines is about the worst you can possibly do for readability.
Just keep the damn comments inline and use colors/font-faces/fold markers to make it readable.