Despite our best intentions we can not always guarantee that the documentation relating to our application will always be available, locatable or made available when needed. A solution to this is using our comments in code to document our application. What sort of comments make for good documentation: - Descriptions of routines.
- Descisions made and options rejected.
- Emails.
- Error messages.
- User comments.
- Application notes.
- Competition solutions and options.
- URLs.
- Rule numbers and headers from specifications.
There is a variety of comment-able documentation. Descriptions of a routine are a given. Emails? Emails upon important decisions can be kept within a module for reference by other code comments describing why a particular piece of programming chose a certain route, for example: Private Sub csv_file_extraction() 'design decision: csv format was chosen. See email_notes.email_22 End Sub Application notes can be a module with comments upon the entire application about decisions taken, important requirements and unresolved issues all in one place. IDEs like RealSoftware's REALBasic IDE provide 'Notes' within each module and class so a developer can keep notes in one place without having to hunt through the application's code for them. Regarding comments for updates, this is a redundant use of code comments, after about 20 updates the prior comments are totally pointless as whatever updates have been made are most likely functioning fine and it is not likely we can magically undo months of updates using the undo function. I would suggest forgetting the update comment list and invest in Visual SourceSafe or some other source code versioning software. Update comments can be handy in a multi-developer environment but again used sparingly and once a couple of changes have gone through a routine we might as well remove the comments altogether. Persistent exceptions/errors are worth commenting upon if they persist despite our best efforts to resolve them. We can record the error details in comments as close as possible to the lines of code where the exception or error is invoked. Along with the error details should be an explanation of why we think the error occurs and a description of our attempts to resolve the error and the results therefrom. We could write the detail within an 'Application Notes' module and a reference to those details near the application code where the error occurs. Competitor solutions to problems could be noted in routines. We do not need to know what their code is to perform certain functions but we can note what they do, for example, the options they provide during a printing routine. If we know that our competitor's application gives the user the option of printing to PDF or WMF format and we can not do this, we can remind ourselves of this option by commenting the routine that deals with printing. In the future when we upgrade we will see this comment and remind ourselves of these options and may even have the answers for them or have time to develop them. URLs are always handy to include in code comments. Say we are using a VBScript COM object to perform some work within an application written in another language, it would be handy for another developer or ourselves if we wrote in the URLs of pages and sites we used for language references and code clips (snippets) during the development of the application. If we are following a requirements specification then it is a good idea to enter the headings, or numbers of each specification requirement into routines describing the requirements a routine is satisfying. This way a developer can look up the specification (if available) for further information. Finally documentation comments should be easily recognisable from other forms of code comments. A simple documenting comment signifier like a hash or three d's after the comment character can make it easy to find documentation comments or extract them via a script if desired. Comments can be used for many things, they do not have to be used to explain what the code is doing (the way we name our routines should do that). These are some ideas upon using comments to document the development process of an application which is more accessible and relevant to the developer than chasing documentation elsewhere. |
Main
