Something I have learnt the hard way: Comments are bad for you. I used to be a big proponent of comments too, until I realized that having the right variable a

Something I have learnt the hard way: Comments are bad for you. I used to be a big proponent of comments too, until I realized that having the right variable and function names makes for much better documentation. Any time a chunk of code gets complicated enough for you to feel you need to comment it, you should just abstract it into another function. If you look at arc.arc it is very much written in this fashion. The problem with comments is that they are not tightly coupled to the implementing code .. if someone comments something and then someone else comes along and changes the code without changing the comment, and then someone else comes along and tries to figure out the code by reading the comment ...