[aasasd]

It's not really the same: documentation that's tied to code structure tends to describe what code does instead of why it exists and how it works on a larger scale. That's why I prefer (additionally) having plain-human-language descriptions separated from the code―it forces the perspective of an external user, at least a little.

This is a gripe of mine especially with inline comments that are too often as useful as this:

    // increments the counter
    i += 1

At the same time, the ‘self-documenting code’ crowd forget that code can't really describe the rationale for its existence and e.g. the expected sequence of calls to its public functions, so plain-language descriptions are still necessary even if the syntax of the chosen language approaches English.

[Jtsummers]

I agree completely, but as a maintenance coder I often don't inherit good documentation. Typically, by the time it hit my shop the code "documentation" was doxygen or similar auto-generated documentation. It showed the program structure but not why it happened. When I do this I don't just tear the code apart. I explain the rationale (as I understand it):

  * can_send: () -> bool
  =can_send= will signal =true= if the conditions are correct
  for transmitting a message over the radio. Otherwise, it'll
  transmit false. Here are the conditions that it checks:
  - Condition :: description
  - Condition :: description
  If any of these are true, then we can transmit.
  #+BEGIN_SRC C
    // body of can_send
  #+END_SRC

With perhaps more levels to my org tree structure if appropriate. Perhaps one of those conditions is particularly complex, I'd give it its own explanation.

If I have a system spec, which in my field I usually do, I'll try to relate it back to the specific requirements or specification elements that this code is implementing.

  - Condition :: description, which maps to Requirement SRD-1010.
  * Message Y
  // description of the message format
  // code for packing it or the class struct or whatever

So the first pass is more "what does this do", second pass is "why does it do it". Again, it's because of where I'm coming from, always late to the party. If I were doing a project from scratch, I'd try to keep the "why's" present more than the "what's".