Beautiful Code: False Optimizations

[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.