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.
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.