Source Code as Documentation
Some great advice from Nigel Jones over at Embedded Gurus:
I've mentioned several times in this blog that the main purpose of source code is not to generate a binary image but rather to educate those that come after you (including possibly a future version of yourself). You may or may not subscribe to this belief. However once you realize that source code often has a life of decades, and that the same source code may end up in dozens of products, then perhaps you may start to change your mind.
- Place all the implicit information in main.c. Why is this you ask? Well if I was to dump three source hundred files on you, which one would you look at first? (An acceptable alternative is to state in main.c that useful information may be found in file X. Be aware however that non obvious source files sometimes get stripped out of source code archives).
- Include in main as a minimum information about the compiler (including its version), the intended hardware target, and how to build the code.
- Think for a minute or two about all the other information you are implicitly using in writing the source code and building it and take the time to include it in main.c. Typically this includes additional tools, scripts etc.
Thinking of your source code as a "message to the future" is something I started doing awhile back, and it really does make a huge difference when you return to an old project years down the road, or even when you attempt to "recycle" old code into a new project.
All those little "obvious" assumptions you had about how the code worked, and even how to recreate it, and things that you brain just loses over time -- dropped bits in a data packet, you might say -- so having all those little build notes organized in one place can be amazingly helpful.
Yes, it takes a little time to set up and document all that, but it'll likely save time and money down the road, and the time you save will likely be your own.
Read Nigel's full post: Considerate coding.