5 ms·

I hate this left/right code documentation fad with passion. Making my eyes jump horizontally across the page every few lines is about the worst you can possibl

by moe 12y ago

I hate this left/right code documentation fad with passion. 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.

seanmcdirmid 12y ago
Do you also prefer footnotes and sidebars inline when reading articles? 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.
- wingerlang 12y ago
  How about toggle-able comments?
  - seanmcdirmid 12y ago
    Inline comments are a part of the code's core layout, so you get into trouble when you make them disappear (as is the trouble with most folding systems). 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.
    - sillysaurus3 12y ago
      Why are people trying to make comments disappear? They are there for a reason. I agree with what moe is saying, though not moe's tone.
      - seanmcdirmid 12y ago
        Comments get in the way of the flow in reading code; they are often of little value that easily goes negative when they distract.
        function_seven 12y ago
        My biggest pet peeve is docblocked-to-death code, like 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.
        deleted 12y ago
        [deleted]
- moe 12y ago
  Do you also prefer footnotes and sidebars inline when reading articles? 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.
- swhipple 12y ago
  Not the parent, but I prefer footnotes/sidenotes when reading physical texts, but prefer inline commentary when reading on the computer screen. Jumping up and down to read a footnote (either manually scrolling or with a hyperlink) or having the sidenotes take up a large percentage of the screen is disorienting for me. 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.
  - seanmcdirmid 12y ago
    That is why side notes are so nice: you don't have to scroll down, you just look at the side bar. And if you just want to read code...hide the side bar! Horizontal real estate is not a big deal with 80 column code widths (you could even have two or three screens of code on one monitor still). Heck, you could render the comments with a proportional font to save even more H-space (fixed-width fonts are extremely archaic). Programming should move out the typographical stone age into something a bit more modern.
    - swhipple 12y ago
      I see where you're coming from regarding ease of hiding/unhiding comments, but I think it'd be quite hard to do correctly in user configurable environments. 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-compare http://learnyousomeerlang.com/starting-out-for-real#bool-and...
clay_to_n 12y ago
I find it far more readable. Anyway, next to where you clicked Annotated Code there's a link for Raw Code which has the comments in-line if you prefer that. You can use an IDE or web editor to get the font colors nice.

by moe 12y ago

seanmcdirmid 12y ago

Do you also prefer footnotes and sidebars inline when reading articles? 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.

wingerlang 12y ago
How about toggle-able comments?
- seanmcdirmid 12y ago
  Inline comments are a part of the code's core layout, so you get into trouble when you make them disappear (as is the trouble with most folding systems). 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.
  - sillysaurus3 12y ago
    Why are people trying to make comments disappear? They are there for a reason. I agree with what moe is saying, though not moe's tone.
    - seanmcdirmid 12y ago
      Comments get in the way of the flow in reading code; they are often of little value that easily goes negative when they distract.
      - function_seven 12y ago
        My biggest pet peeve is docblocked-to-death code, like 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.
      - deleted 12y ago
        [deleted]
moe 12y ago
Do you also prefer footnotes and sidebars inline when reading articles? 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.
swhipple 12y ago
Not the parent, but I prefer footnotes/sidenotes when reading physical texts, but prefer inline commentary when reading on the computer screen. Jumping up and down to read a footnote (either manually scrolling or with a hyperlink) or having the sidenotes take up a large percentage of the screen is disorienting for me. 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.
- seanmcdirmid 12y ago
  That is why side notes are so nice: you don't have to scroll down, you just look at the side bar. And if you just want to read code...hide the side bar! Horizontal real estate is not a big deal with 80 column code widths (you could even have two or three screens of code on one monitor still). Heck, you could render the comments with a proportional font to save even more H-space (fixed-width fonts are extremely archaic). Programming should move out the typographical stone age into something a bit more modern.
  - swhipple 12y ago
    I see where you're coming from regarding ease of hiding/unhiding comments, but I think it'd be quite hard to do correctly in user configurable environments. 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-compare http://learnyousomeerlang.com/starting-out-for-real#bool-and...

clay_to_n 12y ago

I find it far more readable. Anyway, next to where you clicked Annotated Code there's a link for Raw Code which has the comments in-line if you prefer that. You can use an IDE or web editor to get the font colors nice.