SitePoint Sponsor

User Tag List

Results 1 to 4 of 4

Hybrid View

  1. #1
    SitePoint Member
    Join Date
    Apr 2005
    Posts
    3
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Need help in documenting asp application

    Can anyone please guide me in documenting an asp application. The application is all about creating a website for a school. What are the key things to be included in the document?? and how can i document it??? there are many templates that i found.. But i want a sample document done for asp to create a webpage....pls....can anyone help me

    thanx in advance
    completelynew

  2. #2
    Afrika
    Join Date
    Jul 2004
    Location
    Nigeria
    Posts
    1,737
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Are u making comments in your code ?
    if thats it, then use this
    <%
    'comments go here
    %>

  3. #3
    Xbox why have you forsaken me? moospot's Avatar
    Join Date
    Feb 2001
    Location
    Clearwater, FL
    Posts
    3,615
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    There are many different ways to do it, but you should make it clear as to what your code is supposed to do.

    Code:
    <%
         'grab A value from form
         a = request.form("firstval")
    
         'grab b value
         b = request.form("secondval")
    
         'Add A and B together
         c = a + b
    %>
    Take a look at these links for some more info

    http://www.atgconsulting.com/aspstandards.asp
    http://msdn.microsoft.com/library/de...guidelines.asp
    http://msdn.microsoft.com/library/de...guidelines.asp
    http://blogs.msdn.com/brada/articles/361363.aspx
    Last edited by moospot; May 2, 2005 at 12:41. Reason: typo

  4. #4
    SitePoint Member
    Join Date
    Aug 2004
    Location
    Portsmouth, Hampshire, UK
    Posts
    9
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    It really does depend what the client want to see, although as a developer the kind of things I like to see in a document are things like, again where these things are is upto you, but I prefer to see some in the code, and all in a seperate word document so its easy to refer to.

    1) For each page a list of form variables, and what each one is for

    2) For each commonly used function, a little bit about what each function is for, and what each of its parameters are and how they are used, also importantly I find is how the function reacts to an error IE does it raise an error, does it return a special value etc etc.

    3) If a database is used, some kind of database diagram that shows the relations

    4) A list of the commonly used stored procedures, what they do, and what each parameter is and how they are used, again include error information

    5) If any 3rd party components are used, document where they came from

    6) A little FAQ of common problems/common maintance issues, such as if you need to change the DB location where do I do that

    7) Useful although rarely done is a good CSS style guide that says what style is used for a particular purpose.

    Its not a complete list but they are the basics I put in my documentation before a handover, but mostly you put everything you think you would need to know if someone had just given this project to you to work on.

    For some this is rehashing the comments that should be in the code to begin with, although the actual documention should be an enhancement of the comments in the code, and it brings the ASP layer and the DB layer into one place.

    Personally I've always prefered a nice word document that I can flick through rather than having to look at code, to see how a system works.

    If your thinking about comments in the ASP code itself, I find the best way is to make your code as self-documenting as possible, you can do this by

    1) Making all function names meaningful

    IE

    dosomething is a bad function name
    DisplayContactRecord is a good function name (Assuming it does actually display a contact record anyway)

    2) Make your variable names meaningful

    IE

    Dim a, b, c

    c = a * b

    That above code fragment would need some kind of comments so you could understand what a, b and c were, and why you would put a * b into c.

    Dim hourlyRate, hoursWorked, netPay

    netPay = hoursWorked * hourlyRate

    Now that doesnt need much in the way of commenting at all

    3) If you cant make names meaningful, for example a piece of client side Javascript you want to make complicated to understand so people dont steal it, make sure somewhere there is a explaination of what it does.

    Again there are loads more of these kind of things around, I would recommend a book called Code Complete by Steve McConnell (The second edition is better, you should be able to get then 1st edition cheap now and a lot of the advice is the same).

    Jen


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •