Reply to post: Re: If it was hard to write, it should be hard to understand!

A developer always pays their technical debts – oh, every penny... but never a groat more

Claptrap314 Silver badge

Re: If it was hard to write, it should be hard to understand!

This thread seems to only accidentally touch a critical issue: documentation of code itself generally is technical debt. Allow me to explain.

One of the basic rules of XP is "Don't repeat yourself." This is a central tenant of maintainability. The code itself is already a communication. According to Knuth, successive programmers should be the primary targets of this communication. Documentation outside the code source is a second communication. This is why in much of the ruby community, documentation is considered a code smell. "If you need to explain it, you need to simplify it."

The Apprentice/Journeyman/Master distinctions matter. Documenting the business case that lead to a particular implementation is a very different matter. Doing this can help later programmers understand when things really have changed.

Of course, for real-time code, or for the implementation of complex algorithms, the balance changes. But even then, the correct solution is likely to be pointers to timing analysis work and or algorithmic descriptions.

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon