What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 130 Stack Exchange communities.

When I provide a lengthier code snippet, I'm never sure whether it's easier to understand if I splice the comments into the code, or if I leave the code in one block and break it down afterward.

I personally, find the later clearer, but the norm on SO seems to be the former.... so I wanted to find out what everyone else thinks.

For example (pretend the whole thing is longer)

Comment spliced in:


....
  // Add a sum method to Arrays
  // this is a useful function that we'll probably.... 
  // blah blah blah about 2-4 lines of comments sometimes
Array.prototype.sum = function(){
    var sum = 0;
    // Go through each element and add it to the running sum
    for(var i = 0; i < this.length; sum += this[i++]);
    return sum;
}
....

vs

A breakdown after the chunk of code:


....
Array.prototype.sum = function(){
    var sum = 0;        
    for(var i = 0; i < this.length; sum += this[i++]);
    return sum;
}
....

The breakdown:

  1. Create a method to sum the elements of an array. This is a useful function that we'll probably.... blah blah blah about 2-4 lines of comments sometimes.

    Array.prototype.sum = function(){
        ...
    }
    
  2. Go through each element and add it to the running sum

    for(var i = 0; i < this.length; sum += this[i++]);
    

Some notes:

  1. Sometimes if the code is longer, the code alone won't trigger the vertical scrollbar for that chunk, but the code + spliced in comments will trigger a vertical scroll bar.

  2. The whole post is shorter overall with spliced in comments, since you don't have to repeat the same lines of code twice.

  3. It's easier to read through code without any interruptions (w/o any comments)

  4. Spliced in comments provide immediate reference / explanation without having to scroll / move your eyes too much.

share|improve this question
1  
I usually insert comments into the code unless they are too long –  NullUserException อ_อ Sep 13 '10 at 23:30
4  
Heck. I just realized that I misunderstood the question. After I cast an unwarranted close vote. Please ignore it. –  dmckee Sep 14 '10 at 1:06

2 Answers 2

I definitely prefer short comments in the code, long explanations outside of the code.

share|improve this answer

Both.

Describe the code in the code: using the code itself when possible, with comments added as necessary. If I'm writing an answer to a "beginner" question, I'll tend to load up on the comments, just to avoid encouraging the "cargo-cult" mentality of copy-paste programmers: ideally, the reader will actually learn something from the code, even if the rest of the post is ignored.

Describe the algorithm / technique outside of the code. Here's where you can give a high-level overview of your solution, include links to your sources, diagrams, etc. Make the most of the presentation options that Markdown gives you.

Please, please avoid the trap so many programming books fall into, where you present a gigantic block of code and then try to explain it. At least in a book I can dog-ear the pages to make flipping back and forth practical; on SO I'm stuck scrolling, and quickly lose context.

share|improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .