smells-and-heuristics-comments.markdown

@@ -5,13 +5,16 @@
 
  [:arrow_left: Introduction](smells-and-heuristics-introduction) | [Comments :arrow_right: ](smells-and-heuristics-comments)
 
-# 17 Smells and Heuristics
+# Comments
 
-In his wonderful book [Refactoring](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672), [Martin Fowler](http://en.wikipedia.org/wiki/Martin_Fowler) identified many different "[Code Smells](http://en.wikipedia.org/wiki/Code_smell)." The Iist that follows includes many ofMartin's smells and adds many more ofmy own. It also includes other pearls and heuristics that I use to practice my trade.
+__C1: Inappropriate Information__
 
-I compiled this list by walking through several different programs and refactoring them. As I made each change, I asked myself why I made that change and then wrote the reason down here. The result is a rather long list of things that smell bad to me when I read code.
+It is inappropriate for a comment to hold information better held in a different kind of sys- tem such as your source code control system, your issue tracking system, or any other record-keeping system. Change histories, for example, just clutter up source files with volumes of historical and uninteresting text. In general, meta-data such as authors, last- modified-date, SPR number, and so on should not appear in comments. Comments should be reserved for technical notes about the code and design.
 
-This list is meant to be read from top to bottom and also to be used as a reference.
+
+__C2: Obsolete Comment__
+
+A comment that has gotten old, irrelevant, and incorrect is obsolete. Comments get old quickly. 1t is bestnot to write a comment that will become obsolete. If you find an obsolete comment, it is best to update it or get rid of it as quickly as possible. Obsolete comments tend to migrate away from the code they once described. They become floating islands of irrelevance and misdirection in the code.