Technical debt is not the only monster we have to fight – it has a hidden evil twin, as pointed out by Niklas Björnerstedt: Competence Debt. The rope of ignorance that binds our hands and suffocates us by fear so that we don’t dare to change the system. Technical debt makes change difficult because the structure of the system does not support it. Competence debt makes change difficult because we do not know the system well enough, what & where to change and what impacts a change may have.
There is an often neglected tool at our fingertips that might help us fight competence debt. Its name is – behold – JavaDoc. An example from practice: I have returned to a client after two years and needed to understand the functionality of a part of the system. And, to my surprise, I found my own JavaDoc providing exactly the answer I was looking for. A colleague of mine mentioned that I should get the award for the “most documenting developer”. But I don’t do it for fun or just to help my bad memory and to be nice to my colleagues. It is an important contribution to the fight against the ever growing hydra of legacy code. Next time you code, try to remember that you are not typing code, but fighting. As every fight, it is hard – but do not give up or the enemy will prevail.
Side note: Writing JavaDoc that helps yet is not too verbose and not too likely to get outdated soon is hard. Getting the right balance – neither too little nor too much, focusing on the why and the broader context and relationships instead of the changing implementation etc. is difficult. But it is worth it. Help yourself, help your fellow colleagues, strike the hydra. Write good JavaDoc.
PS: This post is about competence debt even though the title mentions technical debt, sorry for the confusion (even though they are two sides of the same coin). And “good enough” documentation, though important, is not the sole remedy, as well as developers’ lack of knowledge is not the sole cause of competence debt. Also, Niklas provides a more in-depth review of the technical & competence debt terms in Misunderstanding technical debt (tech. debt as evolving understanding [but not code] and crappy code). He wrote also A deeper look at Competence debt.
The Iterate Blog 
JavaDoc tends to make this kind of debt worse in my experience, because it inevitably becomes outdated, and as soon as maybe 5% of the docs in a codebase are outdated all the documentation becomes worse than useless because you can’t trust any of it. Better to write unit tests that cover what a piece of code is supposed to do and what it is (and isn’t – strict mocks are your friend here) supposed to interact with. Better still, give your functions and variables readable names so that it’s clear what a given piece of code does, and observe proper separation of concerns in your design.
Thanks for comment, m50d! I agree completely – yet disagree.
I agree that the things that can be documented by tests and good names should be documented that way and that we should avoid putting things that are likely to change into javadoc (or clearly mark them as such if the temporary value of it is worth it).
But there are things that those tools cannot document – f.ex. document why things have been done in a particular way and how does it fit into the bigger context and business needs. (It is a similar challenge as the one I addressed with “public tests” in “Never Mix Public and Private Unit Tests!” (http://theholyjava.wordpress.com/2011/10/20/never-mix-public-and-private-unit-tests/))