Despite our best intentions we cannot always ensure that the documentation concerning our application will remain accessible, locatable or made accessible when required. A solution for this is using our comments in code to record our program. What sort of comments make for great documentation:
- Descriptions of routines.
- Decisions made and choices rejected.
- Error messages.
- User comments.
- Application notes.
- Competition solutions and alternatives.
- Rule numbers and headers out of specifications.
Regarding comments for upgrades, this is a redundant use of code remarks, after about 20 updates the previous comments are entirely pointless as whatever updates are made are most likely working fine and it is not likely we could magically undo months of upgrades using the reverse function. Many would suggest forgetting the upgrade comment list and put money into Visual SourceSafe or source code versioning software. Update comments can be useful in multi-developer surroundings but used sparingly and after a few changes have gone through a regular we might also get rid of the comments altogether.
Persistent exceptions and errors are worth commenting upon should they persist despite our best attempts to resolve them. We can record the error details in remarks as near as possible to the lines of code where the exception or error is invoked. Together with the error details ought to be an explanation of why we believe the error occurs and a description of our efforts to solve the error and the results there from. We can write the detail inside an application notes module and a reference to all those details close to the program code in which the error occurs.
Competitor answers to issues could be noted in routines. We do not need to understand what their code is to execute particular functions but we can note what they do, by way of instance, the options they supply during a printing pattern. If we know that our competitor’s program provides the control flow obfuscation user the option of printing to PDF or WMF format and we cannot do so, we could remind ourselves of the option by commenting the pattern that manages printing. In the future once we upgrade we will see this comment and remind ourselves of those options and might even have the answers for them or have the time to develop them.
URLs are always handy to add in code comments. Say we are using a VBScript COM object to do some work in an application written in another language, it would be useful for a different programmer or ourselves if we wrote in the URLs of WebPages and websites we used for speech references and code clips snippets through the creation of the application.