Question

Best Practices for writing comments in ASP code?

Asked by: BuddhaNature

My team is about to start a large ASP based project and I would like to hear recommendations on best practices for including well written comments within the code so that all team members can be in sync.

This Question has been solved and asker verified All Experts Exchange premium technology solutions are available to subscription members.

Subscribe now for full access to Experts Exchange and get

Instant Access to this Solution

  • Plus...
  • 30 Day FREE access, no risk, no obligation
  • Collaborate with the world's top tech experts
  • Unlimited access to our exclusive solution database
  • Never be left without tech help again

Subscribe Now

Asked On
2007-09-17 at 17:51:39ID22834858
Tags

ASP

Topic

Active Server Pages (ASP)

Participating Experts
4
Points
500
Comments
6

Trusted by hundreds of thousands everyday for fast, accurate and reliable tech support.

  • "The time we save is the biggest benefit of Experts Exchange to Warner Bros. What could take multiple guys 2 hours or more each to find is accessed in around 15 minutes on Experts Exchange." Mike Kapnisakis, Warner Bros.
  • "Our team likes having a resource that is more secure than just using Google and most experts using this service really know their stuff. It's nice to look here first versus using Google." Dayna Sellner, Lockheed Martin
  • "Anytime that I've been stumped with a problem, 9 out of 10 times Experts Exchange has either the accepted solution or an open discussion of the potential solution to the problem." Kenny Red, eBay Inc.

See what Experts Exchange can do for you.

Got a question?

We've got the answer.

Experts Exchange has been collecting answers to technology questions since 1996…3 million and counting! If you have a question, chances are we already have your answer.

Screenshot of Experts Exchange Knowledgebase

Need individual assistance?

Our experts are ready to help.

If you can't find the exact answer you're looking for, ask our exclusive community of 50,000 experts. You’ll get a personalized answer from a trusted professional.

Screenshot of Experts Exchange Knowledgebase

Want to learn from the best?

Read articles from industry experts.

Thousands of free tech tips, tricks, how-to’s and tutorials are available in our peer reviewed articles section. See for yourself how smart our experts are, no login required.

Screenshot of an Article

Working on a long term project?

Store your work and research.

Save solutions to your questions, answers you’ve discovered through searching plus helpful articles in your personal knowledgebase for easy future access.

Screenshot of Experts Exchange Knowledgebase

Access the answers to your technology questions today.

Subscribe Now

30-day free trial. Register in 60 seconds.

What Makes Experts Exchange Unique?

Members of the expert community talk about why the experience at Experts Exchange is different than what you will find anywhere else.

Trusted by the world's most respected brands.

image of each brand's logo

Faithfully serving IT professionals since 1996.

Experts Exchange Logo

Try it out and discover for yourself.

Subscribe Now

30-day free trial. Register in 60 seconds.

Related Solutions

  1. practicing CGI
    Hi there, I wanna learn CGI and PERL...but i dont know how I can use CGI cause i heard that you requires a webserver or something like this for running CGI scripts.... I have window's 95 and frontpage '98 installed in my system...so can u give me the idea how can i learn and...
  2. How can I practice my ASP skills?
    Hi, I want to start learning how to creat ASP in the near future, I know how sweet it looks. I have some experience in VB and I don't know jack about ASP. I was recommended the book ASP unleashed. With what program do you create ASP sites? (Is interdex one of them?). And ...
  3. Best Practices
    I am trying to benchmark Internet best practices in terms of Security, Scalabilty, Performance, Stabilty, Managabilty and Functionlity. I am looking for some pointers where i can get info on the above mentioned 6 dimensions with respect to User, business and data layers.
  4. Bad Practice...
    this is probably bad practice but I've got a question on the IIS area which I need a quick answer to but as it's not heavily watched and the large majority of people using ASP also use IIS I was hoping for some help... http://www.experts-exchange.com/Web/Web_Servers/IIS/Q_20...
  5. ASP Best Practice Guide
    Im looking for an online 'best practice guide' to programming in ASP. Not an ASP source code site but one that outlines how code should be written and how ASP projects should be developed. There are lots of these for CSS, Accessibility and HTML but I cant find one for ASP. ...

Free Tech Articles

  1. WARNING: 5 Reasons why you should NEVER fix a computer for free.
    It is in our nature to love the puzzle. We are obsessed. The lot of us. We love puzzles. We love the challenge. We thrive on finding the answer. We hate disarray. It bothers us deep in our soul. W...
  2. SCCM OSD Basic troubleshooting
    SCCM 2007 OSD is a fantastic way to deploy operating systems, however, like most things SCCM issues can sometimes be difficult to resolve due to the sheer volume of logs to sift through and the dispe...
  3. Migrate Small Business Server 2003 to Exchange 2010 and Windows 2008 R2
    This guide is intended to provide step by step instructions on how to migrate from Small Business Server 2003 to Windows 2008 R2 with Exchange 2010. For this migration to work you will need the fo...
  4. Create a Win7 Gadget
    This article shows you how to create a simple "Gadget" -- a sort of mini-application supported by Windows 7 and Vista. Gadgets can be dropped anywhere on the desktop to provide instant information, ...
  5. Outlook continually prompting for username and password
    There have been a lot of questions recently regarding Outlook prompting for a username and password whilst using Exchange 2007. There are a few reasons why this would happen and I will try to cover t...
  6. Backup Exchange 2010 Information Store using Windows Backup
    There seems to be quite a lot of confusion around the ability to backup Exchange 2010 using the built in Windows Backup feature. This stems from the omission of this feature prior to Exchange 2007 s...

Cloud Class Webinars

  1. Avoiding Bugs in Microsoft Access
    Alison Balter takes and in-depth look at avoiding bugs in Access. In this webinar you will learn about using the immediate window to debug your applications, invoking the debugger, using breakpoints to troubleshoot, stepping through code, setting the next statement to execute, ...
  2. Top 10 Best New Features in Visio 2010
    Scott Helmers gives live demonstrations of the top 10 new features in Visio 2010. This webinar will teach you how to create compelling diagrams by adding shapes to the page with a single click, linking the shapes in a diagram to data in Excel (or SQL Server, or SharePoint), ...
  3. IT Consultant Business Secrets Revealed
    Michael Munger, Experts Exchange tech pro and IT consultant, pulls back the curtain on his very successful businesses and answers question on every IT consultant and business owner should know about. He shares secrets on what he did to solve the 5 most common problems in IT, ...
  4. Disaster Recovery and Business Continuity
    Quest CTO, Mike Billon, gives an overview of the steps involved in building a dunamic disaster recovery plan. Through case studies and an examination of software/hardware tooles for monitoring and testing, you'll gain a better understandin of where you are, where you want ...
  5. Organize Your Visio Diagrams with Containers and Lists
    Scott Helmers uses cross functional flowcharts, wireframe diagrams, data graphic legends and seating charts to teach you: how to ustilize all three new structured diagram components in Visio 2010, the best practices for organizeing shapes in previous version of Visio, how to organize ...
  6. How to Us Objects, Properties, Events and Methods in Microsoft Access
    Alison Dalter gives an in-depbth look at objects, properties, events and methods in Microsoft Access. In this webinar you will learn about using the object browser, referring to objects, working with properties and methods, working with object variables, understanding the ...

Join the Community

Give a Little. Get a Lot.

Join the community of experts here and help other tech pros by answering question in your area of expertise. You can earn FREE access to all Experts Exchange's premium features and resources.

Join the Community

Answers

 

by: NicksonKohPosted on 2007-09-17 at 18:28:29ID: 19909623

Hi BuddhaNature,

Urmm... This is gonna be tough. Almost everyone have their own style and I rarely see ppl following such a rule.

The most common is to write an overview at the top of the page to describe the purpose of the page. Other than that is to write comments on each section of the code especially those places with more complicated logic. I also find SQL comments to be one of the most important.

Cheers,
NicksonKoh

 

by: RedKelvinPosted on 2007-09-17 at 18:35:59ID: 19909647

Generally what you do is put a flower box at the top of the page, like this, quite self explanatory

  ' **************************************************************
  ' *               Page: pagename.asp                                                                       *
  ' *      Arguments: arg 1 - arg 1 description                                                         *
  ' *                         arg 2 - arg 2 description                                                         *
  ' *      Written By: name                                                                                      *
  ' * Created Date: 19 Aug 2007                                                                           *
  ' *     Description: description of the page purpose                                             *
  ' *                                                                                                                        *
  ' * Updated By         Date         Modifications                                                       *
  ' * -----------------  -----------  ------------------------------------------                           *
  ' **************************************************************

Then above each funcion/sub you can do the same, or just use a one liner

' This is a comment to describe a sub

All other comments are generally 1 liners

RedK

 

by: bugsPosted on 2007-09-18 at 01:49:56ID: 19911149

@BuddhaNature,

As described and ilustrated by @RedKelvin, the flower box is self explanatory and you got to keep adding whenever you make some changes....like when the page was first created...then after the first release keep adding the modifications done in brief....need write the complete detail there instead which ever line you keep changing just append the release number/author name/purpose as below....

<%
'###### This code Belongs to BUGS ##########
'#Changes for release v1.1
'#Purpose :
'======Script START HERE=======

..

..
..

'======Script END HERE=======
%>


Comments are self explanatory, so more the merrier....it forms a kind of detailed documentation for the page...

But makesure your developers or team members write there name and purpose of the change in the code...thats a must to do....

 

by: topazgPosted on 2007-09-18 at 08:56:01ID: 19914041

You may also want to look at a versioning system such as Subversion if you are going to have multiple people working on it - there's nothing quite as irritating as over-writing each others' work :)

Subversion link: http://subversion.tigris.org/

Works as stand-alone system, if you have an Apache server with .php (which I'm guessing you may not if you are doing an .asp project) you can also do full releases to online ftp servers using subversion.

As a Windows Client I personally recommend tortoiseSVN (http://tortoisesvn.tigris.org/).

One of the great advantages of using SVN (or CVS or other systems) is it records exactly what has changed and by who, and allows people to revert to old versions -- I find this indispensable for my projects, others may find it unnecessary :-)

Not a comment for points btw, just for helping project management / commenting generally!

 

by: NicksonKohPosted on 2007-09-18 at 17:45:39ID: 19917637

Yes, over commenting is also a big problem as the code becomes to read. Individual coder has to know how to strike the right balance as to how much to comment and when to overwrite old comments. As said earlier, there is a tendency for individual programmers to stick what they are most comfortable with.

I personally dislike keeping history of comments and just retain the latest comment. I even delete the old incorrect codes and just keep one backup copy. There is also the daily, weekly and monthly tape backup but this codes backup are not immediately accessible and will only used in critical situations. Lastly, without the distraction of old comments, retaining only just the latest comment also makes the code much quicker and easier to read for understanding the code in entirety. I must stress again, you must understand your own preference and then dictate a style which your programmers should try to stick to.

cheers
Nickson

 

by: RedKelvinPosted on 2007-10-06 at 04:14:51ID: 20027185

Hi there,
How are you going, any updates? Have any of the suggestions helped?

RedK

20120131-EE-VQP-002

3 Ways to Join

30-Day Free Trial

The Experts

98% positive feedback on 31,087 answers since March 2000. angeliii is a Microsoft Most Valuable Professional for his work with MS SQL Server & Develoment.

He has also proven his knowledge of Visual Basic Programming, PHP Scripting and Oracle Databases.

The Experts

97% positive feedback on 10,752 answers since July 2000. lrmoore has more than 18 years experience in the networking industry.

The six-time Mircosoft MVPs specialties include firewalls, virtual private networking, and network management.

Testimonials

"...and excellent source for support... Kind of like having your very own IT dept." Electriciansnet

Testimonials

"I was apprehensive at signing up at first. However... it has already made my life as an IT administrator much easier." JaCrews

Testimonials

"WOW! You guys have great, active, and knowledgeable people on here." moore50

Business Clients

Business Clients

In the Press

"If you’ve got a question... Experts Exchange can supply an answer.”

In the Press

"...an invaluable aid for both IT professionals and those who require tech support."

In the Press

"where IT professionals provide quick answers on just about any topic"

Business Account Plans

Loading Advertisement...