When you update the code that the comment references, you usually have to update the comment as well.
If your comments are that detailed, you're doing it wrong.
If you're writing in C, do yourself a favour and check out this editor: http://www.geany.org/
It's the slickest C editor that I've ever had the pleasure of using. It seems little-known, though, and I don't know why.
(It handles other stuff than C too, but I haven't used it for any of those yet.)
Christ, I know everyone has their own personal style and everything, but this is just pernicious. In any case, the author gives the game away: when he thinks code is overcommented, he can ask Emacs to hide the comments. So far as I know there's no automatic system that will generate the comments that the author failed to put in because the code was "self-documenting". This is particularly important when you're working with anything other than standard libraries --- you might know what "libfzp_inc_param_count_fast", but your reader probably won't.
Right now I'm working on a crypto library that incorporates a lot of very specific elliptic curve operations. My technique is to comment the hell out of every damned interesting piece of code on the assumption that a picky reader can turn off the damned comments if they get in his way. In fact, there are various places where I've actually scaffolded all of the comments before writing a line of code. Doing otherwise would have been an enormous headache and made bugs a whole lot more likely. And this way even a non-expert should be able to understand the entire program flow.
Unfortunately, one of the previous pieces of software in this area followed the poster's "self documenting code" style (very nice, clean, well written code with no comments), and even I find it difficult to piece together what's going on in places --- not because all of the code is crypto-specific, but because the author has thrown so much effort into writing "clean, pretty" code that it's actually hard to know where the crucial pieces are. I can't quite explain why I find this so irritating, but perhaps some of you will know what I mean.
That's easy: http://www.guidebookgallery.org/screenshots/win31
Does anyone else get queasy looking at Windows 3.1?
Just check out the differences between say, x264 and apples encoder...
Aren't you comparing x264 to oranges?
If I were a grave-digger or even a hangman, there are some people I could work for with a great deal of enjoyment. -- Douglas Jerrold