I have spent my career listening to people talk about their self-documenting code. I had some colleagues who built a sophisticated graph (nodes and links) analysis and visualization environment that consisted of something like 100K lines of Java. They didn’t document anything. They are brilliant software engineers, but their code is extremely difficult to support now that they have moved on to other jobs.
There is no self-documenting code. I was going to include a very elegant little piece of code that implements the wavelet lifting scheme and a linear interpolation wavelet. The code is so simple and elegant, surely you would understand it.
It should be obvious that this is not the case unless you are already familiar with wavelet signal processing and the wavelet lifting scheme algorithms.
The claim about self-documenting code is a line that software engineers use to be lazy. And in most cases the code is anything but self-documenting.
Documentation must be maintained along with the code. I have also frequently seen this excuse that documentation should not be included with the code because over time it becomes incorrect. That’s nothing more than an excuse for not writing documentation. Maintain the code, maintain the documentation.
If you can’t bring yourself to write documentation for the people who have to maintain your code in the future, write it for yourself.
I have often found bugs in my code when I documented it. In writing what I intended the code to do, I have discovered that, in fact, it doesn’t do that.
When I go back to my code months later, after I have forgotten about what I was doing, I can read the comments to remind myself. And if the comments are inadequate, I can improve them.
The design of nderground is complex. nderground was designed, from the start, to be a scalable, secure, social network that gives its users privacy. nderground uses a variety of Amazon Web Services components including Elastic Beanstalk, RDS/Postgres and DynamoDB. I have been building nderground for over two years.
I have probably written a book so far of design notes and notes on the various components. By writing notes, I only have to learn the details of an AWS service once. Anyone I work with can read my notes and learn about my design thinking and the implementation details. This means that I spend less time explaining the software.
What would you think of a scientist who did not keep an extensive lab notebook? The fact is, the scientist would be completely unsuccessful. Or a mechanical engineer designing a bridge. Should they build a self-documenting bridge.
If you are a disciplined professional, in any area, you keep extensive notes and documentation. This is just a simple fact. The unfortunate practice of software engineers to not document their work is inexcusable. This reflects a lack of science in computer science and a lack of engineering in software engineering.
I’ve used nderground as an example here. If you want to see what I’m talking about, go to http://www.nderground.net. There is a “request an invitation link” at the bottom of the page.