Practices of an Agile Developer

  26   Communicate in Code

“Comments should help out when the code is too tangled to read. Explain exactly what the code is doing, line by line. Don’t worry about why; just tell us what on Earth it’s doing.”

Programmers generally hate writing documentation. That’s because most documentation is kept separate from the code and becomes hard to keep up-to-date. Besides violating the DRY principle (Don’t Repeat Yourself, in The Pragmatic Programmer: From Journeyman to Master [HT00]), it can lead to misleading documentation, which is generally worse ...