Code Documentation Debate

Code never lies, documentation/comments/etc. sometimes do.

But documentation is often not code.

Code can show you HOW something is done. Only documentation can explain WHY it is done that way.

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:<c

Yes, with code documentation write "why" not "how."

Make it clear that documentation is part of the code. Missing or poor docu = code not acceptable.

Documentation isn't a substitute for reading the code, and the best place for documentation is in the same file as the code.

Self-documenting code typically can answer "How", but not always "Why"

"Self documenting code" often isn't, in my experience

Yes yes yes a million times yes.I need this engraved into the skull of every tech lead that claims the code is the documentation.The engraving will be appropriately referenced.It will also link to another engraving that documentation is good actually.