How Should Code Be Written and Documented?

Here's some traditional advice about writing code and documentation:

• Choose good names for classes and methods and functions and modules and whatever other things can have identifiers in the programming language of choice.
• Write comments in the code to explain stuff.
• Don't write too many comments.
• Write additional documentation in files in the same directory structure as the source code and subject to the same source control (not on the company's network drive, please!!).

The Need for a Test Reader, to Test the Quality of your Documentation

That was great advice, but even if you do all the things listed, how do you know you've done them well enough?

Ideally, you need feedback from a test reader.

This test reader is:

1. Someone familiar with the programming language
2. Someone familiar with any major libraries used by the code
3. Someone who understands what the code is supposed to be doing
4. Someone who would have been qualified to write the code in the first place
5. Someone who did not actually write the code, and therefore is not already familiar with all the intimate details

The ideal test reader is just like you, except for that last criterion.

Unfortunately, in the real world, everyone is too busy to help you with something as unimportant as the readability and clarity of your code.

So you try to do it yourself, that is, read your own code and comments and documentation, and try to spot all the places where perhaps you haven't been as clear as you could be, and fix up any problems found.

The Reason Why You Cannot be the Test Reader

But of course you will fail, because you know too much.

You know too much, which means that you can't easily judge how readable your code and documentation is to someone else who doesn't already know everything that you know.

How maybe you can be the test reader ...

But wait. There is a possible solution.

Which is: wait six months.

Or more precisely: finish your coding project, don't touch it or look at it for six months, and then read it to see how well you can read it.

How to give feedback to yourself

So, you've waited six months. You've read your own documentation. You've spotted a few issues, and now you need to give feedback to the developer who wrote the documentation.

Unfortunately, the original developer is no longer there to hear your feedback, because the original developer is yourself six months ago, and you don't have a time machine.

So you will have to make do. You, six months later, will have to do your best to fix the problems with the code and documentation where it has not been written clearly enough. You will have to investigate everything about the code that is not sufficiently clear to you, and you will have to fix it. Where "fixing" might be choosing better names for things, or writing better comments, or writing comments that should have been written but weren't written, or, in some cases, writing additional documentation in separate non-source files (but still in the same directory structure and source control).

Once you've done all these fixes, you will then have two choices, depending on whether or not you have a good regression suite:

• You have a regression test suite so comprehensive that it guarantees that any changes you have made to the code for the sake of clarity have not in any way broken its functionality. So run it, and then re-deploy, or re-release, the "fixed" version of the software. Or,
• You don't have a good enough regression suite, so it's not worth the risk of redeploying your "fixed" source code. Instead, save the "fixed" version of the code and the documentation into a different branch of the source repository, for developers to reference in the future, and hopefully, to use as a starting point if any major changes are to be made to the software in the future.

In Summary

So, here is the plan for writing documented code which is sufficiently well written and clearly documented:

1. Write the code.
2. Maybe document some of the code as you go along.
3. Test the code, deploy the code, distribute the code, whatever ...
4. Before concluding work on your 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.
5. Wait six months. (Do something unrelated to that particular project.)
6. After six months has passed, revisit the project, and read through all the code and the comments and the documentation.
7. 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.
8. Then, either:
   • Run a full regression test suite (if indeed you have a regression test suite that would give you sufficient confidence to release an updated version of the software knowing that you are providing no direct benefits or improvements to actual users of the software) 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.

TL;DR

How to write your code and documentation so that it can be read by other developers in the future: give it to your future self to read, ask your future self to give feedback about the readability of the code, and, since (at that later time) your earlier self no longer exists, ask your future self to fix any problems found.