Well, I think the first thing is quit cross posting, and sending duplicates.
Secondly, the word standard just doesn't sit well with me.
If I'm going be accused of proposing something by golly I'm going to do it,
and you can't stop me and you probably will groan when I'm done, hopefully
anyway.
Now if you've gotta have something that your going to force people to do why
not go all the way and make everybody miserable.
Lets all start doing PDL documentation except we'll use Hal's fusedoc as the
PDL header section. PDL is really neat was first developed what? in 1974 (I
was three then).
Oh yeah PDL stands for "Program Design Language" (I think) and is kind of
like pseudo code, but isn't so low level and mustn't contain keywords that
are specific to just one language. You do a header section at the top kind
explaining what the whole page is going to do in general terms (Fusedoc).
The you write out the logic of the program in the order its going to apply.
After all that is done, you make them all comments and seperate them with
spaces, and you've just successfully documented your entire application.
Now all you have to do is fill in the actual code underneath each commented
line. Piece of cake the module is practically written and you don't even
have to think about it anymore, just write code. Now sinse I'm proposing
this and its going to make everybody miserable, I might as well make myself
miserable and do a proper example. I know what I'll do a simple shopping
cart, maybe someone will need one, and it'll have most of the functions in a
shopping cart tag.
<!--- End of Rant, now for some real fun --->
Step 1 ( Write out the PDL, the opening stuff will be the responsibilities
section of the fusedoc in the end)
I will be a shopping cart for an Ecomerce Store. I will be able to receive
an items number, quantity and cost. If someone decides later on that they
want to add more to any single item, I have to handle that without creating
another record. I will mark items as inactive if I'm asked to delete one of
them.
Begin
Initialize variables I need ItemNumber, Quantity, Price, Active, CartAction.
Case CartAction = Add
If Not Defined Cart
Initialize Cart
If Not Item already exists
Create new row for item
Add Item, Quantity, Price, and make Active
Else If Item Exists
Find Item and Update quantity
Case CartAction = Delete
IF NOT Item Exists AND NOT Item Active
Do Nothing, The user is obviously on drugs
Else IF Item Exist AND NOT Item Active
Still do nothing, Maybe I should try what the user is taking
Else IF Item Exists AND Item Active
Update Item to Inactive
End
There we're all done with step one. We've defined what the purpose is and
we can easily read what the flow and logic of the module is going to be.
For the next step we need to comment and space out the lines and they become
our documentation of the program logic. Nothing is specific to Cold Fusion
syntax and its all written in plain english that any junior, senior,
maintenance, structure, or chaos programmer can understand, hell I be their
boss could understand what's going on.
Step 2 (comment it all out and create the fusedoc at the top for the
header)
<!--- Fusedoc
||
shopCart.cfm
||
Version: 1.0
||
Responsibilities:
I will be a shopping cart for an Ecomerce Store. I will be able to receive
an items number, quantity and cost. If someone decides later on that they
want to add more to any single item, I have to handle that without creating
another record. I will mark items as inactive if I'm asked to delete one of
them.
||
File Author: Fred T. Sanders
||
File Status: Under Review
||
Assigned To:
||
Edits:
||
Notes:
||
--> attributes.item {Product ID for a catalog item}
--> attributes.qnty {Product Quantity}
--> attributes.price {Product's Cost per unit}
-->? attributes.active {Cancel order for this line item}
--> attributes.CartAction {What I'm being asked to do}
<-- session.qry_Cart {Session scoped recordset holding our shopper's items}
||
END FUSEDOC --->
<!--- Begin --->
<!--- Initialize variables I need ItemNumber, Quantity, Price, Active,
CartAction. --->
<!--- CASE CartAction is "Add" --->
<!--- IF NOT Defined Cart --->
<!--- Initialize Cart --->
<!--- IF NOT Item already exists --->
<!--- Create new row for item --->
<!--- Add Item, Quantity, Price, and make Active --->
<!--- ELSE IF Item Exists --->
<!--- Find Item and Update Quantity --->
<!--- CASE CartAction is "Delete" --->
<!--- IF NOT Item Exists AND NOT Item Active --->
<!--- Do Nothing, The user is obviously on drugs --->
<!--- ELSE IF Item Exists AND NOT Item Active --->
<!--- Still Do Nothing, Maybe we should try what the user is
taking --->
<!--- ELSE IF Item Exists AND Item Active --->
<!--- Update Item to Inactive --->
<!--- End --->
There all done with Step 2. We can safely assign this to somebody else to
do if we really wanted to. We know exactly what needs to be done. Our hands
are really tired now but that's okay we all know we're going to have
authoritis when we're old and cobwebby coders anyway. So lets quit wasting
time and get to work.
Step 3 (actually writing the code)
<!--- Fusedoc
||
shopCart.cfm
||
Version: 1.0
||
Responsibilities:
I will be a shopping cart for an Ecomerce Store. I will be able to receive
an items number, quantity and cost. If someone decides later on that they
want to add more to any single item, I have to handle that without creating
another record. I will mark items as inactive if I'm asked to delete one of
them.
||
File Author: Fred T. Sanders
||
File Status: Under Review
||
Assigned To:
||
Edits:
||
Notes:
||
--> attributes.item {Product ID for a catalog item}
--> attributes.qnty {Product Quantity}
--> attributes.price {Product's Cost per unit}
-->? attributes.active {Cancel order for this line item}
--> attributes.CartAction {What I'm being asked to do}
<-- session.ShopCart {Session scoped recordset holding our shopper's items}
||
END FUSEDOC --->
<!--- Begin --->
<!--- Initialize variables I need ItemNumber, Quantity, Price, Active,
CartAction. --->
<cfparam name="attributes.item" default="">
<cfparam name="attributes.quantity" default="">
<cfparam name="attributes.price" default="">
<cfparam name="attributes.active" default="1">
<CFSWITCH EXPRESSION = "#attributes.CartAction#">
<!--- CASE CartAction is "Add" --->
<CFCASE Value="Add">
<!--- IF NOT Defined Cart --->
<CFIF NOT isDefined('session.ShopCart')>
<!--- Initialize Cart --->
<CFSET session.ShopCart=querynew("item, quantity, price,
active")>
</CFIF>
<!--- IF NOT Item already exists --->
<CFIF NOT
ListFindNoCase(Valuelist(session.ShopCart.item),attributes.item)>
<!--- Create new row for item --->
<cfset temp=queryaddrow(session.ShopCart)>
<!--- Add Item, Quantity, Price, and make Active --->
<cfset temp=querysetcell(session.ShopCart, "item",
attributes.item)>
<cfset temp=querysetcell(session.ShopCart, "quantity",
attributes.quantity)>
<cfset temp=querysetcell(session.ShopCart, "price",
attributes.price)>
<cfset temp=querysetcell(session.ShopCart, "active",
attributes.active)>
<!--- ELSE IF Item Exists --->
<CFELSE>
<!--- Find Item and Update Quantity --->
<CFSET position = ValueList(session.ShopCart)>
<CFLOOP FROM="1" TO="#ListLen(position)#" INDEX="Counter">
<CFIF ListGetAt(ValueList(session.ShopCart.item), Counter)
IS trim(attributes.item)>
<CFSET newqnty =
ListGetAt(ValueList(session.ShopCart.quantity),
Counter)+trim(attributes.quantity)>
<CFSET temp = QuerySetCell(session.ShopCart, "quantity",
newqnty , Counter)>
</CFIF>
</CFLOOP>
</CFCASE>
<!--- CASE CartAction is "Delete" --->
<CFCASE Value = "Delete">
<!--- Update Item to Inactive --->
<CFSET position = ValueList(session.ShopCart.item)>
<CFLOOP FROM="1" TO="#ListLen(position)#" INDEX="Counter">
<CFIF ListGetAt(ValueList(session.ShopCart.item), Counter)
IS trim(attributes.item)>
<CFSET temp = QuerySetCell(session.ShopCart, "Quantity",
'0' , Counter)>
<CFSET temp = QuerySetCell(session.ShopCart, "Active",
'0', Counter)>
</CFIF>
</CFLOOP>
</CFCASE>
</CFSWITCH>
<!--- End --->
All done, now my hands are really friggin tired. But there's my proposed
"standard" of writing code if your really so hell bent on have a "standard"
way of doing it.
I presented this in a sarcastic manner mainly because I'm Fred and the
thought of writing out this much extra commenting is a horrid thought.
However, it is a good system and if your crew or company or whatever needs
to spell everything out its not a bad system. If anybody wants to the see
the really outdated original paper on PDL here's a link:
http://www.cfg.com/pdl81/pdlpaper.html
Now I'm going to watch a band or something.
Later Guys and Gals,
Fred
----- Original Message -----
From: "Lee Borkman" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]>
Sent: Sunday, August 27, 2000 11:45 AM
Subject: Standard Source Documentation System: A new thread
Hi all,
Our old thread, "Documentation System for Cold Fusion", seems to have
wandered, as old threads are wont;-)
Perhaps we might start afresh. There seems to be some confusion about
proposed standards, etc, especially since Fred denies having any proposed
anything (I think).
---------- clip clip -------------
------------------------------------------------------------------------------
Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/cf_talk or send a
message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
