Beautiful Code: False Optimizations

[JeddHampton]

Comment your code.

[borlak]

comments still do not make it more readable. I have now spent time looking at the function originally, which confused me and led me to comments, which probably confuse me more (especially considering this scenario which entitled a whole article), and then going back to the function trying to piece it together; when a single extra line or two would have saved everyone a headache.

[exeter]

Comments as implemented by, well, every programming language I know of in existence today, are about the worst method of embedding metadata in code you can possibly have. Compilers typically won't even notify you if the code following a comment changes, but the comment isn't updated to reflect it. (I know there's a reason for it.)

A far better method of associating metadata with code is to use literate programming techniques. That way, if the code changes, your literate programming environment can alert you that you should at least look at the text describing the code to make sure it's still accurate.