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 B4A2C8D6 F2 E5 G2 H1 I3 J9 Dependent Events Independent Events

4 THE FUSEBOX PATH Data Model & Schema Fusebox Architecture Fusedocs Queries/ Sprocs PrototypeWireframe Queries/ Sprocs Queries/ Sprocs Fusestubs Query Sims

5 THE FUSEBOX PATH Data Model & Schema Fusebox Architecture Fusedocs Queries/ Sprocs PrototypeWireframe Queries/ Sprocs Queries/ Sprocs Fusestubs Query Sims

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. HTML Layout Query Sims 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: || 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 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: || 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 ::= “ || BEGIN FUSEDOC ||” [ ]; ”|| Responsibilities ||” ; [ ]; ( ) ::= “|| ” “ ||” [ ] ; “|| ATTRIBUTES ||” ; ( ) ::= ::= “--> “ | ” ” | ”++>” | ” ”.”] [“]”] “:” [ ] ; “|| END FUSEDOC ||” ; “--->”;

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: Revised: changed to default badLogin to || FUSE_PROPERTIES || FusedocSpec:c:\properties\default.cfm Level: 1 HasForm: TRUE Jsrequired: 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? <!--- || 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 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 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? – Hal Helms, Fusebox architect – Jeff Bane, database architect – Aaron Newman, layout specialist – A Philippines-based CF shop were coders

21 DOES IT WORK? 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 Judith Martin “Developing Applications with ColdFusion & Fusebox”, developed and taught by Hal Helms Oct 16-20, Tampa, FL for more info