How Should Code Be Written and Documented?
There are many opinions about how to write code so that it can be understood by developers other than the original developer (or developers). There are opinions on how much effort should be put into the choices of names of variables and classes and methods and functions and modules and whatever other things can have identifiers in the programming language of choice.
There are opinions on how many comments there should be in the code, and how much effort should be put into writing good comments, and what things need to be commented and what things don't need to be commented. And there are opinions on what additional documentation should be written that exists outside the source code itself.
Many developers seem not to care that much about code readability or documentation quality. But even if you are one of those developers that does care, it can be harder than you realise to write code and code comments and other documentation so that the code is as readable and understandable as it possibly can be.
(Note: not all code documentation is actually in the code, but to keep things simple, I am going to limit myself to talking about code documentation that is either comments in the code itself, or maybe, written documentation contained in files in the same source directory, i.e. not very far away from the code, and subject to identical source control.)
The Final Judge
The final judge of your code and its comments and documentation is the person who has to read it.
We do not necessarily require that anyone be able to read and understand the code.
The ideal test reader of source code for a project is:
- Someone familiar with the programming language
- Someone familiar with any major libraries used by the code
- Someone who understands what the code is supposed to be doing
- Someone who would have been qualified to write the code in the first place
- Someone who did not actually write the code, and therefore is not already familiar with all the intimate details
In an ideal world, you would write your code and you would write and edit your code comments and other documentation, and you would present this allegedly readable and well-documented code to the ideal test reader, and the ideal test reader would complain about any aspect of the code or the documentation which was not clear, and in response to the test reader's feedback you would fix up any problems.
But sometimes it's not that easy to get hold of such an ideal test code reader, and even when you can, that person may not have the time to spare.
A Later Version of Yourself As A Test Reader of Your Code
It has been noted that most of the criteria for an ideal test reader of the source code are satisfied by the person who wrote it, six months later. The first four criteria are automatically satisfied, and the last criterion is close enough to being satisfied because most coding involves a lot of detail which a developer is not going to remember that well once he or she has stopped working on a project.
When you try to read your own code that you wrote six months ago, it will seem like you are reading code that someone else has written. You will be totally at the mercy of the quality of that coder's coding and their documentation, and you will be in a good position to offer feedback about the readability of that code and documentation (except, of course, who are you going to offer that feedback to? – but I will get back to that).
So, Plan B is, ask yourself six months later to read your own code and documentation and give feedback on the readability of that code and documentation.
Of course right now, as you are writing your code, you are not yourself six months later, and when you are working on something, it's very hard to imagine your own ability to understand the results of your own work six months later. Because it's hard to imagine yourself as a person who does not know the things that you know now. So right now you can't be yourself six-months-later, and you can't even pretend to be yourself six-months-later.
The only way to know how well your own self can read your documented code in six months time is to wait six months. And then read it.
But, of course, at that point the original you is no longer able to respond to any complaints or questions from the six-months-later version of you.
After six months, the only person who can fix up any code problems is the six-months-later you.
And if that six-months-later you is going to fix up any problems, that later you is going to need all the help they can get from the earlier you. So even though the original you cannot know how to write code and documentation that is maximally readable for the later you, the original you still needs to make some attempt at maximum readability. And hopefully that will be good enough that the later you, with not too much additional effort, can reconstruct any details missing from the code as written and documented, and the later your can fix up the code and the documentation so it is as readable as it should be.
The Final Plan
So, here is a final plan for writing documented code which is sufficiently well written and documented that it can be read and understood by yourself six months later:
- Write the code.
- Maybe document some of the code as you go along.
- Test the code, deploy the code, distribute the code, whatever ...
- Before concluding work on the project, revisit the code and document it as well as you can, keeping in mind the six-months-later you who is eventually going to read it.
- Wait six months. (Do something unrelated to this particular project.)
- After six months has passed, revisit the project, and read through all the code and the comments and the documentation.
- Identify any problems of readability. Investigate all questions where the answers are not obvious in the code or the documentation. Tidy up the code and documentation accordingly.
- Then, either:
- Do a full regression test suite, if indeed you have such a regression test suite that gives you sufficient confidence that you feel happy deploying or releasing an updated version of the code that has no new functionality and doesn't fix any bugs, and then deploy or release the updated version, or,
- Save the updated better-documented version of the code in a separate branch of your code repository, so it can be readily referenced by any future developers or maintainers of the code.
(Note: ideally the later you would only alter comments and separate documentation, and there would be no risk at all in deploying or releasing the changed code. But, in practice, even changing comments carries some risk of accidentally changing the code, and also, quite often, code is not clear because it has not been written in the best possible way, and really you want to fix those problems by rewriting the code. So, in general, you will be well-advised to regression test the code before deploying or releasing the updated version.)
TL;DR
Write code and documentation that's good enough for your future self by actually getting your future self to read it and, if necessary, get your future self to fix any problems that they find.