Do Developers Dream of Self-Documenting Code?

DZone 's Guide to

Do Developers Dream of Self-Documenting Code?

Why is it really necessary to write the documentation? This author debunks the most common excuses from developers about creating proper documentation.

· DevOps Zone ·
Free Resource

Most software developers I’ve met during my career don’t love writing documentation. When they are forced to write it by company procedures, by the customer or by an external requirement, usually the result is not so great.

The typical reasons given by the developers include:

  • My writing skills are poor.

  • I hate writing.

  • Nobody reads the documentation.

  • I have no time to write it.

  • It’s not my job.

  • Writing code is more important than writing docs.

Since so many people dislike writing documentation, I’m wondering: is it really necessary to write it?

Many statistics indicate that the maintenance of code has a very important role in the development of a software. Among the items that weigh more in the maintenance of the code, we find the lack or shortage of documentation and the difficulty of understanding the code.

So, having the documentation that explains what the code is doing should mitigate the cost of software maintenance.

Image title

As Tom DeMarco wrote in “Why Does Software Cost So Much?” (Dorset House, 1995): "There are two familiar variants of the documentation problem: a) you write all the internal documentation that you know you need and you pay a terrible price for it, or b) you don’t write all the internal documentation you need and you pay a terrible price for that."

The documentation has a cost, not only a cost of writing, but also a maintenance cost itself. If the documentation is not aligned with the code, it may worsen the situation.

Of course, in case of mismatch between the documentation and the code, the latter has the final say. So, again, does it make sense to write technical documentation of a software?

One of the principles of the Agile Manifesto states: "Working software over comprehensive documentation."

This statement is taken literally as an authoritative source of the uselessness of writing code documentation. Hence the slogan: “the code is the documentation;” the dream of most developers: not having to deal with documenting their code.

Actually, it is a misinterpretation of the Agile principle, which, as in the other principles, does not say that the documentation has no value, but its value is lower than having a working software.

The idea of having an eloquent code is undoubtedly fascinating. It would allow the developer to focus on software development, surely a more familiar task, and would avoid the cost of having to produce an additional artifact to maintain over time.

But in everyday life, is the code produced by most of the programmers really understandable so as to be proper documentation? Is the dream of having a self-documenting code actually achievable? Can we find a realistic compromise between code and documentation production?

Leave your thoughts in comments.

agile, clean code, coding, devops, documentation, software development

Published at DZone with permission of Andrea Chiarelli . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}