Web Application Development Advice & How To
Active Server Pages Development Advice & How To

Shining Star Services LLC
Shining Star Services
ASP.net Articles
HTML Tutorial
Auto-select an Element from a Menu or Scrolling List & Save Keystrokes!
ASP Driven DHTML Slider Menus REVISITED One Year Later! Part II
ASP Driven DHTML Slider Menus
ASP Driven HTML Outlines
Reusing Code with ASP Include Files and Subroutines
Hacker Query Check
.htr IIS Security Issue
Databases, Cookies
Functions to Open a Database Connection and Record Set
Setting Up and Using OraSession to Manage Your Oracle Database Objects
Storing Non-Durable Data for Cookie-less Sessions
Smart Popups
Javascript: Validate Numeric Fields
Javascript Confirm Form Submission
Javascript Dynamic Text Area Counter
Javascript: Check All and Uncheck All Check Boxes
Javascript Field Validations -- Client Side Scripting
Tree Select Demo
Adobe Extension Manager
Scandisk & Defrag Pointers
Standards & Style
Setting Up Your Own ASP Development Templates
Creating a Project Template for Estimations of Time, Tasks, and Resources
To Host or Not To Host
ASP Naming Conventions
HTML Naming Conventions & Visual Interdev HTML Generation
Working with and in spite of the Visual Interdev Design Mode
Commenting Your ASP Source Code
Reader Letters

Articles Home

Shining Star Services

Commenting Your ASP Source Code
By Nannette Thacker - 05/01/1999

At the top of each web page, I like to include ASP comments which include the file name, the developer name, the create date, and the purpose of the page. What you choose to include in your comments may differ, but the point is to make it easy for you or your team members to come back to the code later and make easy alterations and updates.

' LinkPage.asp
' Developer: My Name
' Date: 03/15/1999
' Purpose: The purpose of this page is to
' provide links to other related web sites.
When changes are later made to the code, you should add version number, alteration date, your initials, reason for the change and/or a description of the modifications made.

' 2.5 5/2/99 NKT Added a page counter to the bottom of the page.

When a new version is released, and the report is turned in that since the new release a new bug has occured on suchandsuch.asp page, you can easily go into the source code, search for the version, date, or your initials, and find all changes made.

Even during development, you may wish to search all changes you made today. You can easily search for "5/2/99 NKT" and find every change made in all files!

Some developers prefer including modification comments in the Comment Header at the top of the page, following the "Purpose." However, I prefer embedding these comments within the code right where the change was made. This comes in handy when doing merges of two differing documents. You can view the two versions side by side and also see the comments as to why the change was made. If commented properly, the person performing the merge can easily see where the change starts and where the change ends.

Functions also need to be documented. Whether you have a single quick function included in the page itself, or whether you put it in an include file (suggested), you should comment the function describing its purpose and how it is called.

When you come back to maintain the code a year later, you will thank yourself. Other users who attempt to maintain your code will thank you as well. I once had a developer approach me in a grocery store parking lot and thank me for my well documented source code, which enabled her to easily take over where I had left off.

When documenting source code, don't forget to update existing comments if the code change causes the description to be inaccurate. Always make sure the description still describes the new functionality.


ShiningStar.net | ShiningStarSingles.com | Christian911.com