[lifebeyondfife]

Don't want to start an argument but perhaps why it's rare to see is because many people realise commenting on code as a rule leads to: https://twitter.com/nzkoz/status/538892801941848064

Commenting on the purpose of a file is reasonable, as it explaining why a piece of code works the way it does e.g. if an external constraint is in play. But explaining how in code comments is redundant if the code is well written and the functions and variables are well named.

[openasocket]

I'd mention one exception: when you're doing something very complicated in a single function. For instance, I recently had to write an algorithm that involved partitioning integers into intervals, and the solution was a very non-intuitive dynamic programming algorithm. I devoted several paragraphs of documentation to the how's and why's, along with additional comments every couple lines. I found it really useful, especially when I had to go back and fix an odd off-by-one error that only occurred in certain cases. In those situations, variable names can only help so much.

[darfs]

Thing here is, it can replace any Blog/Book/Posts whatever about RSS Parsing with Nodejs And a line-by-line documented Code is in such a case a better solution for those who want learn by reading Code :-) Surely, it's worse in big Projects. But there I miss often a detailed documentation about the implementation. Look for example to the strlen() Std implementation for C/C++(it was the same with Magic Hexcodes and so on, right?)

[filipedeschamps]

Totally agree! But basically this is a tutorial.