Solution To This Documenting Comments Within Code...

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 sorts of comments make for good documentation:

1. Descriptions of routines.

2. Descisions made and options rejected.

3. Emails.

4. Error messages.

5. User comments.

6. Application notes.

7. Competition solutions and options.

8. URLs.

9. 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.

by: hasan

POST COMMENT

With Extenze Male Enhancement Regain the Lost Vigour to Spice up the Married Life When Your Girlfriend Wants Space – How to Keep Her in Love With You 13 Relationship Tips For Men Who Might Need Some Books About Relationships Signs Your Husband Doesn’t Want You Anymore – Helpful Advice for Married Women Baby Bereavement,Birth of a Stillborn Baby Preparaton,funeral for baby Conventional Medical Equipment Financing and Leasing, Application Only and Full Documentation Programs Federal Reserve Malinvestment Using Big Breast Forms -- Enjoy the Painless Way of Breast Augmentation 4 Crucial Sciatica Home Treatment Tips - Do you Know Them? When He Says He’ll Call and Doesn’t – Why Men Do This and How to Change It Average Babysitter Pay - What is the Recommended Sitter Fee? Five Boundaries You Must Set to Manage Stress and Be More Productive Impotence Supplements - Why Herbal Cures Are Better Than Prescription Drugs