I'm a self-taught programmer and still learning the fundamentals. Since I work heavily with Microsoft tools, I'm currently using VBA to build small utilities for my day job. These projects are mostly a side responsibility, so I don't have time to maintain extensive documentation, but I'd like someone else to be able to understand and take over the projects if necessary. What is the minimum practical documentation I should create, both inside the code and outside it, without making the process overwhelming?
4 Answers
Clear names are one of the best forms of documentation. Use variable and procedure names that explain their purpose, then add comments only where the reason for the code would not be obvious. Comments should explain why something is done, not simply repeat what the next line does.
Before coding, write down the problem and a rough outline of the solution. Even a few lines of pseudocode can clarify your approach and later serve as useful documentation. In the VBA code itself, add a brief description above each important procedure, explain unusual decisions, and record significant changes when they happen.
Version control can help even if you’re working alone. Keep the code and a simple change log in a repository so you can see what changed and restore an earlier version. Automated tools can help draft documentation, but review everything they produce because generated comments can be inaccurate or become outdated.
Start with a short overview for each project: what problem it solves, how to run it, what files or settings it depends on, and any known limitations. You can keep this in a simple text or Markdown file. You don’t need a large documentation system for small tools.
That helps. I was mainly unsure what information belongs in the documentation rather than which application to use, so a short project overview and change log sound manageable.