p2p.wrox.com: Archives - asp

asp_databases thread: Best practices for documenting ASP

Message #1 by jmuldoon@q... on Tue, 18 Dec 2001 18:58:49

Compared to ColdFusion, ASP-database web pages can create an awfully 

confusing mess, depending on the programmer's approach. As a tech writer 

who's done some ASP programming, I'd like to know if there are any 

recommended protocols for documenting ASP programming so the next person 

will not have to spend a lot of time trying to deduce everything from the 

code with no overview or guidelines.



I know there are database modeling tools, like ERwin, for complex 

databases. But, even with relatively simple databases, ASP can get pretty 

convoluted (again, depending on the programmer).



Does anyone know of a source? Does anyone have opinions on the best 

approach to documenting ASP?



Thanks,



Joe

Message #2 by "Ken Schaefer" <ken@a...> on Wed, 19 Dec 2001 19:56:10 +1100

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From: <jmuldoon@q...>

Subject: [asp_databases] Best practices for documenting ASP





: Compared to ColdFusion, ASP-database web pages can create an awfully

: confusing mess, depending on the programmer's approach.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Only bad programmers write code that is a "confusing mess"



When I write code I hardly have anything free-form inline ASP. Everything is

done by generic routines. Each routine is documented with a change-history,

input parameters, what it returns, and possibly some description of what it

does (that said, each routine should really only do one thing, but do it

well)



For example, a simple page might look like (I put some comments in...)



<%

' Generic routine to verify security

' permissions required for this page

Call VerifySecurity(1, 2)



' Sets standard no-cache & expiry headers etc

Call SetHTTPHeaders()



' Checks for form postback

If not isPostBack() then



    ' Open a connection, get a results-set as an array

    ' and dispose of connection

    Call DBConnOpen(objConn, Application("strDBConnString")



    arrUsers = UserListGetByActiveStatus(objConn, 1)



    Call ObjDispose(objConn, True, True)



End If

%>

<html>

    <body>

        <form method="post">

            <%

            ' Write a select drop down list using our array

            ' Write an submit button

            With Response

                .Write(WriteFormSelectList("cboUsers", "cboUsers", "",

arrUsers, 1, "", ""))

                .Write(WriteFormSubmitButton("btnSubmit", "btnSubmit", "",

"Submit"))

            End With

            %>

        </form>

    </body>

</html>



Not too complex eh? I put some comments in to help...



Cheers

Ken

Message #3 by jmuldoon@q... on Thu, 20 Dec 2001 02:20:13

Thanks, Ken. That's a start.



If you have any old code (nothing proprietary, valuable, full of state 

secrets) that is well structured and well documented, maybe you could send 

me a copy. Otherwise, I appreciate this input.



Joe M.



> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> From: <jmuldoon@q...>

> Subject: [asp_databases] Best practices for documenting ASP

> 

> 

> : Compared to ColdFusion, ASP-database web pages can create an awfully

> : confusing mess, depending on the programmer's approach.

> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> 

> Only bad programmers write code that is a "confusing mess"

> 

> When I write code I hardly have anything free-form inline ASP. 

Everything is

> done by generic routines. Each routine is documented with a change-

history,

> input parameters, what it returns, and possibly some description of what 

it

> does (that said, each routine should really only do one thing, but do it

> well)

> 

> For example, a simple page might look like (I put some comments in...)

> 

> <%

> ' Generic routine to verify security

> ' permissions required for this page

> Call VerifySecurity(1, 2)

> 

> ' Sets standard no-cache & expiry headers etc

> Call SetHTTPHeaders()

> 

> ' Checks for form postback

> If not isPostBack() then

> 

>     ' Open a connection, get a results-set as an array

>     ' and dispose of connection

>     Call DBConnOpen(objConn, Application("strDBConnString")

> 

>     arrUsers = UserListGetByActiveStatus(objConn, 1)

> 

>     Call ObjDispose(objConn, True, True)

> 

> End If

> %>

> <html>

>     <body>

>         <form method="post">

>             <%

>             ' Write a select drop down list using our array

>             ' Write an submit button

>             With Response

>                 .Write(WriteFormSelectList("cboUsers", "cboUsers", "",

> arrUsers, 1, "", ""))

>                 .Write(WriteFormSubmitButton

("btnSubmit", "btnSubmit", "",

> "Submit"))

>             End With

>             %>

>         </form>

>     </body>

> </html>

> 

> Not too complex eh? I put some comments in to help...

> 

> Cheers

> Ken

>

Return to Index

P2P Archives