One of the several C# programs I am working on at the moment were started while I was still learning to write complex programs. Until I am aging out of the workforce, I hope every program I write, is done while I am learning! The thing about learning as you write – especially as a full-stack developer – is that your later code is better organized, better designed, and more robust, than your earlier code.

There are many, many advantages to documenting your code. Even with a great software engineering approach to design, in advance of putting fingers to keys, there will be quirks about your code that will be difficult for later debuggers to decipher. For this reason, people will always tell you to document your code.

But there’s another reason. A reason that I have recently discovered purely by accident; I was documenting my code in the usual way: Comments on lines that may be confusing and triple-slash summaries before functions. But last week I started writing a document with an explanation of each step of each function in my entire program, broken down by class. This is not going to be a quick job – I am sure I have documented less than 1% of one of my programs so far. The process, though, has been very enlightening.

Going through the code, line-by-line, in a systematic way, so that I can re-learn what each function does, how, and why, has helped me:

• Identify new bugs;
• Improve code logic;
• Re-use code; and
• Better organize the code.

This last one is the least important – but functions that are not in a logical order make following the code-flow more difficult. I have moved functions around, just to make the flow more logical, but the first three benefits are the more important.

The bugs I have found are ones that have not manifested, as far as I know, in use by the end-users, but they could have, and so it’s good to clear those out.

Code logic could also manifest in bugs, but it also means that the code might be inefficient (for example, a for-each loop through a whole list twice, or not using a hashset when it would be much quicker).

So, though you have heard it before, I am going to repeat that boring recommendation that a lot of us fail to take heed of: Documenting code is worth the effort, and makes for a better experience not just for those that follow you, and have to deal with your code, but also for you, the programmer.