As a developer, programmer, systems engineer or whatever my code writing colleagues call themselves these days - I have a secret and deep confession to make...
I actually document all of the code I write
Oddly enough, my documentation process not only exists as I code (yes during, after and before), but also in tandem with the design phase to any system or chunk of code I am to write. You may proclaim "BUT how can documentation begin before you write code? Its an easy answer for me, any documentation will explain my systems workings from the microscopic view to the 60K views in the following:
- In CRS/SRS level requirements documents
- Through descriptive module level requirements which may contain my API or application usage
- Data flow diagrams/VISIO etc...
In other words, I design to document and I document the design(TM). If your still reading, here are the four reasons on why I document my code like I do:
- Documentation improves clarity for everyone. If I am away on vacation, my team mates can review my code and understand what is happening. Secondly, I will understand my code after vacation or a long time later after it had been written when I have to inevitably fix a bug or two.
- Documentation improves chances that poor coding will be caught. Perhaps poor coding is a strong phrase, but it might help me or others notice when a function has become too monolithic and needs to be re-factored.
- Documentation is a resume booster or calling card. There is a common thought that if your code is too simple or well documented that there is a possibility that your employers may not need you in the future. This might be true, but even if it is, your invaluable efforts to the team or project proclaims loudly enough that any smart team lead should at a minimum have a look at you. Recommendations from your boss should come easy!
- Documentation shows personal ethic in your work and discipline. If you write good code, make it better code. If you want others to use it, document it.... Be proud of your code!
In my humble opinion, there are no excuses to provide poor or zero documentation. Unit tests, variables, functions and application guides should be clearly and concisely documented while providing an invaluable resource to you and your future. Documentation is a living thing so be prepared to keep updating it, but remember all of the time it will save you later when you forgot an applications inner workings or API usage.
Documentation, do it well or don't bother to code - my mantra