[briandoll]

One solution for this is to use a programming language that is easy to comprehend at a glance, omitting unnecessary "line noise". Ruby is a good example of a very readable programming language, designed for programmer happiness (ie. those that both write and read code all day)

Secondly, a major problem with line-by-line documentation is that you will soon end up in a situation where the documentation does not agree with the code. A bug was fixed, but the comment wasn't updated or vice versa.

Additionally, what makes for good comments in complex systems is not "what" a specific line of code does. Good programmers can read the code they are paid to write in. A good comment identifies "why". Why is this code necessary, why is it being solved in this specific way, why should I, as a developer of this system, care about this code.