4.5. Documentation

Documentation comes towards the end of the list here, but really it underpins all of the aspects of writing software. The code, the .c file(s), doesn’t stand in isolation. It’s paired with documentation which describes the requirements, the architecture, the testing strategy and results, and so on.

Writing a program is a design task - there are usually lots of different ways of achieving the same thing. Documentation helps others to understand how you chose to do it, and why you chose that way. Someone can probably work it out from looking at the code, but that’s a lot of work! It’s much easier for the original author to write down their thinking and decisions.

Remember that the person maintaining your code may in fact be you in the future! If you spend 6 months working on a different project, and then come back to do some bug fixes on a piece of code, almost certainly you’ll have forgotten a lot of details on why things were done the way they were. Future you will thank you for having some good documentation.