How much to comment code sample when writing an article?

Question

When you read a "howto"-style article with a code sample, which do you prefer:

• All the code off to the side with very few comments, and a complete line-by-line breakdown in the article

OR

• All the code off to the side with LOTS of comments, and a complete line-by-line breakdown in the article

The moral of my question: Can too many comments in the code actually reduce readability for unfamiliar code?

EDIT: Assume for the purposes of the question that the article is introducing new concepts to the reader, all the way up to a language with which he/she is not familiar.

Answer 1

Yes, too many comments can reduce the readability of unfamiliar code. They would also be redundant if the article is describing what the code is doing.

Answer 2

I often find it hard to follow line-by-line breakdowns post-code, so I'd prefer paragraph sections of comments before lines of code that are new or particularly interesting given the target of the article.

Answer 3

I would use the same guidelines for commenting code for an article as I would for any other comments I write in code - ideally the code is written such that it is self-commenting. If there is a specific section that needs more explanation, then by all means comment it. For an article, it would also probably be helpful to give an overall explanation of the code either immediately before or after.

Answer 4

Absolutely. It can reduce readability, but same happens with too few comments if the code is not well written.

Anyway, it really depends on the code and the subject. I believe the question is too vague to be answered generically.

Answer 5

Ideally code in articles should be short and with no comments, the code itself should be able to reflect what you are saying in the article itself.

Answer 6

Comments in a "howto" article should be a bit more verbose than in actual code.

Your question is rather open-ended, and doesn't say anything about target audience. If you're writing an article for people who are already programmers, then a good rule of thumb might be just enough commenting so that someone who isn't familiar with the language (but is familiar with programming) can follow it.

If you're doing tutorial style articles for newbies, then the best way that I've seen is a lightly commented, complete code block at the top, and THEN, a line-by-line step-through of the code in the article body. That way, the newbie gets the hand-holding they need, but can still refer to a readable block of code at the top.