One of the first things I learned while being a TA is that when code is not working do not read the comments, read the code. Why is this? The comments lie, more often than not when something is not working the comments will not say the same thing as the code. Why is this? Well the person with the issue in the code does not fully know how to get the code to work and thus will not document the non-working code correctly. If they did know how to get the code to work right they would not need to see a TA.
I find reading the code not the comments to continue to be true in the corporate world. More often then not the comments in the code do not tell the full story of what the code does or the comments are out of date or the comments are just flat out a lie. It is normally, best to just use the code as your guide to what the software is doing (or not doing). This is even true in OSS Projects. These projects are not written by software Gods and more often than not the person doing the documentation is not the same person that wrote the code.
When in doubt (and even when not in doubt) have the code be your guide and pay no attention to the comments. Now this is not to say do not write comments. I myself write comments all the time in my code (even for software that I write for myself). I normally trust my own comments and find them to be helpful for to speak on the reasons I write one line of code over another, but I write my comments in such away as to still let the code speak for it self. After all if the code cannot be read, then it should be rewritten in a readable way.
