anchor.diff:  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.
   
  +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). Their risk of becoming obsolete is therefore
  +higher.
  +
  +To rephrase it, comments like this are part of the problem, 
  +not the solution.
  +
   Inline comments are just a liability.
   
  -The worst part is that comments like this often appear as follows:
  +The worst part is that they often appear as a whole bunch:
   
   [source,java]
   ----
  
positive.code: = Rant: The Teletubbies "Documentation" Pitfall
  
  == Typical example
  
  
negative.code:         }
  ----
  
  == Going further
  
  You could even rewrite the method like this:
  
  [source,java]
  ----
          /**
           * *describes the nominal observable behaviour here [...]*
           */
          public SomeResult computeResult(SomeParameter parameter) {
                  try {
                          Foo foo = _niceService.fetchFoo(parameter);
                          return new SomeResult(foo);
                  }
                  catch (MyNiceServiceException e) {
                          throw new AssertionError("Should not happen", e);
                  }
          }
  ----
  
  Now the assumptions are even more explicit. That opens even an interesting 
  discussion about the virtues of https://www.youtube.com/watch?v=57P86oZXjXs[failing fast] :-)
  
  One could argue we could do even better.
  Ideally, method signatures should be sufficient to tell what the method is doing: http://data.tmorris.net/talks/yow-west-2016/1d388b6263e7cbeedfbea224997648daa1d7862d/parametricity.pdf[parametricity] FTW!
  Hoogle.com is probably one of the best illustrations for this.
  
  That requires discipline (especially with languages such as Java, C# et al), 
  but is not impossible to achieve: try to minimize and contain side effects, 
  forego nulls...
  
  Yet another interesting discussion!
  
  == The end
  
  As you can see, caring about documentation is a gateway drug to better 
  software, clearer releases and happier collaborators.
  
  I personally write 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 not 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 meaningful methods, rename, split 
  expressions... the IDE is your friend). This is the material that
  decays the least, rely on this as much as you can!
  
   - the *-doc (e.g. Javadoc, Csharpdoc): 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!