A Secret Weapon Against Technical Debt
(Cross-posted from blog.iterate.no.)
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.
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.