I would change "All comments are bugs" to "All comments document bugs we have to work around." Otherwise, some maintenance programmer is going to wonder why, only for Solaris, I use poll() on a single file descriptor when I immediately call recvfrom(). With a comment, I can inform said maintenance programmer that under Solaris, the observed behavior is that recvfrom() is NOT a pthread cancellation point, but poll() is, whereas under Linux, revcfrom() IS a pthread cancellation point.
In reading over the comments I've written, a majority of them document the various methods of working around bugs on third party components we can't fix. Ah, the joys of working with proprietary, non-source libraries.
And this sounds more like the why kind of comment rather than the what, which approach I agree with. That is, you are commenting the pieces of code that a reader would say "er, the heck?" with explanation.
In reading over the comments I've written, a majority of them document the various methods of working around bugs on third party components we can't fix. Ah, the joys of working with proprietary, non-source libraries.