anchor.diff:  = Rant: The Teletubbies "Documentation" Pitfall
  +
  +== Disclaimer
  +
  +I am not Uncle Bob's nephew, but if you already have read Clean Code, 
  +chances are you will not learn much from this post.
   
   == Typical example
   
  
positive.code: Well, comments like these can *easily* get out of sync. 
  In the worst-case scenario, they become misleading.
  
  Easily, because comments don't run, they are just an informal bunch
  of text and cannot be changed automatically (at least, not in a 
  100% reliable way). 
  
  To rephrase it, comments like this become part of the problem, 
  not the solution.
  
  It leads to situations where you have to confront the current code
  and the outdated comment and you cannot really be sure which one 
  describes what the behavior *should* be.
  
  Inline comments are just a liability.
  
  The worst part is that comments like this often appear as follows:
  
  [source,java]
  ----
  
negative.code:                 // call nice service to fetch foo
                  Foo foo = _niceService.fetchFoo(parameter);
  
  				// [...] 200 lines with comments+code like that
                  // hilarity ensues... not
                  return new SomeResult(foo, ...);
          }
  ----
  
  Indeed, the bad side effect of this kind of brain-dead comments is
  that it *prevents* the original authors to ask themselves: is the code 
  readable enough this way? Am I thinking this through? How can I make
  the code more self-explanatory?
  
  If you get used to this kind of comments, you will most likely focus
  your reading on them and live in the illusion that the method is 
  readable and well-documented.
  
  I have got some bad news for you: 200 lines of code for a method are
  NOT readable at all, no matter how much obsolete poetry you stick in there.
  