I'm a self-taught beginner who has been learning programming gradually. Since I use Microsoft tools at work, I'm currently writing VBA to build small utilities for my job. These projects are mostly side tasks, so I don't have enough time to create extensive documentation, but I'd like someone else to be able to understand and maintain them if I move on. What practical documentation should I create, both inside the code and separately from it, without making the process overwhelming? I'm especially interested in what information to write—not just which tool to store it in.
3 Answers
A simple project README or handover note may be enough. Include the purpose of the tool, setup requirements, instructions for common tasks, expected input and output, known errors, and who to contact about the business process. Keep a basic change log with the date, what changed, and why. A version-control system or even dated backup copies can help preserve earlier versions, but the documentation itself should stay focused on information a maintainer would actually need.
Clear names are one of the best forms of documentation. Use descriptive names for variables, procedures, worksheets, and controls so the code explains itself. Add comments mainly where the reason for a decision is unclear, rather than commenting obvious statements. Before coding, you can also write a short outline or pseudocode describing the problem and the intended steps. That outline can later become both a guide for you and a useful record for the next person.
Automated tools can help generate a first draft of comments or documentation, especially for repetitive procedures, but review everything they produce. Code changes over time, and automatically generated descriptions can become misleading. The most valuable comments explain why the code works a certain way, what assumptions it makes, and what could break—not merely repeat what the code already says.
That makes sense. I’ll concentrate on documenting the purpose, assumptions, setup, and reasons behind unusual code instead of trying to explain every line.