1
FUSEDOC: AN EMERGING STANDARD
Make everything as simple as possible, but not simpler. -Albert Einstein
2
WHY FUSEDOC?
The purpose of Fusedoc is to provide a standard that will help developers in…– shortening development cycles– reducing development costs– lessen occasion and severity of bugs– make maintenance of programs easier
3
THE CRITICAL PATH
B4A2 C8 D6
F2
E5
G2
H1
I3
J9
Dependent EventsIndependent Events
4
THE FUSEBOX PATH
Data Model& Schema
FuseboxArchitecture
Fusedocs
Queries/Sprocs
PrototypeWireframe
Queries/Sprocs
Queries/SprocsFusestubs
QuerySims
5
THE FUSEBOX PATH
Data Model& Schema
FuseboxArchitecture
Fusedocs
Queries/Sprocs
PrototypeWireframe
Queries/Sprocs
Queries/SprocsFusestubs
QuerySims
6
Dependencies
Dependencies are broken through strong interfaces
Fusedoc provides way to specify the interface of fuses
7
THE GOAL: FUSESTUBS
Fusestubs provide a coder with the fuse layout (HTML/CSS, etc.), any applicable query sims and the Fusedoc needed to complete the fuse.
HTMLLayout
QuerySims
Fusestub
Fusedoc
8
FUSEDOC
When asked what was the most frightening thing he had ever experienced, Mark Twain immediately answered, “a blank piece of paper.”
We have been taught that we should document our code but now how.
9
A SAMPLE FUSEDOC
<!--- || BEGIN FUSEDOC ||
|| RESPONSIBILITIES || I provide the user a login of both userName and password, returning to the fusebox with
an RFA of submitForm. If I get a var called ‘badLogin’, the user is returning to me from an invalid login.
|| HISTORY ||Author: [email protected]
|| ATTRIBUTES ||--> RFA.submitForm: a FUSEACTION--> [badLogin]: a STRING<-- userName: a STRING<-- password: a STRING
|| END FUSEDOC ||--->
10
FUSEDOC DISSECTED
<!--- || BEGIN FUSEDOC ||
|| RESPONSIBILITIES || I provide the user a login of both userName andpassword, returning to the fusebox with an RFA ofsubmitForm. If I get a var called ‘badLogin’, the useris returning to me from an invalid login.
|| HISTORY ||Author: [email protected]
|| ATTRIBUTES ||--> RFA.submitForm: a FUSEACTION--> [badLogin]: a STRING<-- userName: a STRING<-- password: a STRING
|| END FUSEDOC ||--->
Limit
Sections
Limit
11
EXTENDED BACKUS-NAUR FORM DESCRIPTION
<Fusedoc> ::= “<-- <EOL> || BEGIN FUSEDOC ||” <EOL>[<EOL>];”|| Responsibilities ||” <EOL>;<responsibilities-contents> <EOL> [<EOL>];(<section>) ::= “|| ” <section-name> “ ||” <EOL> <section-contents> <EOL> [<EOL>] ;“|| ATTRIBUTES ||” <EOL>;(<attribute>) ::= <identifier> ::= “--> “ | ”<--” | ”<->” | ”+
+>” | ”<++” | ”+++”; [“[“][<scope>”.”]<attribute-name>[“]”] “:” <data-definition> [<attribute-comments>] <EOL>;
“|| END FUSEDOC ||” <EOL>;“--->”;
12
BAREBONES FUSEDOC
<!--- || BEGIN FUSEDOC ||
|| RESPONSIBILITIES || I provide the user a login of both userName and password, returning to the
fusebox with an RFA of submitForm. If I get a var called ‘badLogin’, the user is returning to me from an invalid login.
|| ATTRIBUTES ||--> RFA.submitForm: a FUSEACTION--> [badLogin]: a STRING<-- userName: a STRING<-- password: a STRING
|| END FUSEDOC ||--->
13
CUSTOMIZED FUSEDOC
<!--- || BEGIN FUSEDOC ||
|| RESPONSIBILITIES || I provide the user a login of both userName and password, returning to the fusebox with an RFA of submitForm. If I get a var called ‘badLogin’, the user is returning to me from an invalid login.
|| HISTORY ||Author: 8.8.20000 [email protected]: 9.14.2000 [email protected]; changed to default badLogin to “FALSE”
|| FUSE_PROPERTIES ||FusedocSpec: c:\properties\default.cfmLevel: 1HasForm: TRUEJsrequired: TRUE
|| SPERFIDIES ||Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo.
|| ATTRIBUTES ||--> RFA.submitForm: a FUSEACTION--> [badLogin]: a STRING default=“FALSE”<-- userName: a STRING REQUIRED<-- password: a STRING REQUIRED
|| END FUSEDOC ||--->
14
PARSING ENGINES
Provides ability to view Fusedoc in browser Formal description of Fusedoc provided in
Extended Backus-Naur Form Flexible nature of Fusedoc allows each
developer/shop to define the specification a fuse subscribes to
15
ATTRIBUTE IDENTIFIERS
--> variable explicitly passed in
<-- variable explicitly passed out
<-> pass-thru variable (unchanged)
++> persistent variable already available
<++ persistent variable to be set
+++ additional required files
16
HOW MUCH DOCUMENTATION IS ENOUGH?
Responsibilities should allow a competent CF programmer who is unfamiliar with the application to complete the fuse.
Attributes should outline all variables the coder needs to be aware of. Any variables that exist but are not needed by the fuse can be omitted for brevity and clarity.
17
TEST HARNESSES
Def: A “wrapper” that your fuse slips into, allowing it to be unit tested.
Fusedoc lets you know exactly what the test harness must provide for, making testing much easier and less frustrating
18
DOES IT WORK?
<!-- dspCartSummary.cfm --><!-- [email protected] -->
<!--- || FUSEDOC ||
|| RESPONSIBILITIES ||I show the user's cart summary based on the cookie "cartID" that exists. If no cookie exists, I tell the user they don't have anything in their cart.
|| ATTRIBUTES ||--> RFA.continueShopping: a FUSEACTION --> RFA.removeItemFromCart: a FUSEACTION --> RFA.retotalCart: a FUSEACTION called when the Update_&partID&_&quantity& is changed--> RFA.checkout: a FUSEACTION
<-> fatherID: a STRING <-> fatherType: a STRING ( Certification | Manufacturer | ProductLine | HotDeals | searchString)<-> fatherName: a STRING
<-- partID: PRIMARY KEY from Parts table on RFA.removeItemFromCart
@DeveloperNote: The ampersand indicates that this will be replaced by a value at run time. For example, a valid variable name might be "Update_2107_1" <-- Update_&partID&_quantity: a STRING on RFA.retotalCart (may be multiple)
++> [cartID]: a COOKIE PRIMARY KEY from Carts table.
+++ qryGetCartSummary.cfm+++ incHeader.cfm+++ incFooter.cfm
|| END FUSEDOC ||--->
19
DOES IT WORK?
<!--- || FUSEDOC ||
|| RESPONSIBILITIES ||I first try to get credit card authorization. If it fails, I let the customer know there was a problem and I invite them to try again with RFA.checkoutAgain. If auth succeeds, I call qryInsertOrder.cfm to add an order,
I show the order summary (qryGetCartSummary.cfm and qrymyShippingInfo.cfm) and thank them for their business. I also email an order summary to them and then an order summary to each of the developers who had items in their order. Finally, I clear out the cart (qryClearCart.cfm) and delete the cookie.cartID and the cookie.ShoppingInfo.
|| ATTRIBUTES ||--> RFA.failure: a FUSEACTION
--> shipMethod: a STRING ( GNDCOM | 2DA | 1DA )--> ccType: a STRING ( ax | mc | visa | discover )--> ccNumber: a STRING--> ccExpirationMonth: a STRING (01 thru 12)--> ccExpirationYear: a STRING (2000 thru 2005)--> ccNameOnCard: a STRING--> shipping: a NUMBER--> tax: a NUMBER--> cartSummary: a NUMBER<-> fatherID: a STRING on RFA.failure<-> fatherType: a STRING on RFA.failure
++> cartID: a COOKIE PRIMARY KEY from Carts table++> ShippingInfo: a COOKIE WDDX packet of shipping info
+++ qryGetCartSummary.cfm+++ qrymyShippingInfo.cfm+++ qryInsertOrder.cfm+++ qryClearCart.cfm+++ incHeader.cfm+++ incFooter.cfm+++ PaymentNet: a CFX tag to communicate withe creditcard auth.
|| END FUSEDOC ||--->
20
DOES IT WORK?
www.solutionssite.com– Hal Helms, Fusebox architect– Jeff Bane, database architect– Aaron Newman, layout specialist– A Philippines-based CF shop were coders
21
DOES IT WORK?
www.solutionssite.com, a Sun ecommerce site– Aaron worked with client on look and feel– Simultaneously, Jeff worked on data model while– I worked on overall Fusebox architecture– I created Fusestubs and query sims and sent them off to the Philippines for
coding– We received them back (with test harnesses) and I integrated them and did
integrated testing.– Results:
60% cost savings site was done by moonlighting in one month
22
FUSEBOX TRAINING
If written directions alone would suffice, libraries wouldn't need to have the rest of the universities attached.
- Judith Martin “Developing Applications with ColdFusion & Fusebox”, developed and taught by Hal HelmsOct 16-20, Tampa, [email protected] for more info