Comment by sshine

The problem with "documentation" in commercial code is that nobody reads it.

Any "documentation" that isn't embedded in code will never be opened again.

Any "documentation" in the form of doc-strings and comments will, over time, lie.

This is because competent programmers cannot agree on whether to even comment.

When any large percentage of competent programmers do not comment, it is better to not rely on comments.

Here's another pitch:

  Code-as-Docs