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:         }
  ----
  
  == The end
  
  The information is still there, it has been moved to the right place, 
  that is all.
  
  I personally write inline comments less than 1% of the time I write code. This
  happens where there is a tiny local expression that may seem obscure and
  there is no simple way around it.
  
  For the 99+%, there are almost always better places to write the information 
  you want to convey:
  
   - the code itself, it should answer *WHAT* it does, without ambiguity, 
  else just refactor it (extract meanningful method, rename, split 
  expressions... the IDE is your friend)
   - the *-doc (e.g. Javadoc, C#doc): the information is about the 
  observable behavior of the section you are altering
   - the intent: that should justify the commit you are about to push
  
  Inline comments are (99+%) dead! Long live inline comments!
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.
  