Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Improve Your Code Readability With Fusedoc

Improve Your Code Readability With Fusedoc

I'm writing this prior to the turn of the new year, so I trust that somehow civilization bungled through and that you're not reading this by the light of your last candle, alert to the strange sounds outside your door that are growing ever nearer.

With the new year we're introducing a monthly column dedicated to all things Fusebox. First, I want to thank all of you who attended the Fusebox session at the ColdFusion Developer's Conference in Boston. Over 300 people attended the session ­ and some were turned away for lack of room. While I'd like to attribute that to my galvanic oratorial skills, I suspect that it had more to do with how important the quest is for a methodology that works well with ColdFusion.

Why do we need a methodology? Let me reiterate a little of my presentation at the conference and draw an analogy between the state of programming today and that of rifle making 200 years ago. An odd pairing? Well, consider the similarities:

  • Skilled craftspeople are needed to create the product.
  • Each product is the unique work of its creator.
  • There's a shortage of skilled workers.
  • The quality of finished goods varies widely.
  • Maintenance of our products requires the user to go back to the creator or to employ the skills of a highly paid master craftsperson.
  • There's no ability to interchange parts from one product to another.
  • Division of labor is very limited.
  • The efficiencies of scale are few: making 10 products takes 10 times as long as making one.

    Into this highly inefficient situation stepped an American genius: Eli Whitney. Whitney had already achieved great fame (but not wealth) with his cotton gin. Assessing the situation, Whitney decided that he was just the one to solve the "rifle crisis" and proposed to the new national government that he be awarded a contract to produce 10,000 rifles at a cost of just over $13 each.

    The idea was preposterous ­ but Whitney had already proved his ability to effect miracles. Thus the largest single financial transaction in the young nation's history was agreed upon. Whitney's plan for meeting the contract was to standardize parts so they could be reused among different rifles. The rest, of course, is history. (Perhaps, however, Whitney should be the patron saint of programmers, as he delivered late on the contract.)

    Today we face a "software crisis." According to one magazine, two thirds of corporate software projects are never deployed or are declared failures. I think you'll agree those numbers are stunning. But what else could we expect with the situation outlined above?

    In other issues of CFDJ I've argued that one of the great reasons for Allaire's huge success with ColdFusion is the degree to which it masks complexity from developers, letting them get code out of the programming shop and into use. What we've lacked is a methodology that would direct our programming efforts to produce maintainable, reusable code. I believe that Fusebox goes farther along that path toward radical simplicity in our development efforts.

    If we're to get beyond the practice of "one-off" software, in which each bit of code is written one piece at a time, we need to agree on certain standards. We need to document our code with the understanding that it will be fitted into other applications and maintained by different coders many times during its life. And, as we've just recently seen with the Y2K issue, there's no telling just how long that life may be.

    This is nothing new, of course; we know documentation is good practice. Why, then, is it so rare? Perhaps we feel something like Mark Twain did when he was asked by a reporter whether there was anything he feared. Twain mulled the question over before drawling, "A blank piece of paper." It's intimidating to think we have to engage in writing a novella with every code file. What exactly should we put in it? What format should it have?

    You may already have a standard for documentation. If not, I suggest one for you to evaluate. I call this Fusedoc ­ an appropriate name as the idea was borrowed from its cousin, Java, with its Javadoc specification. Fusedoc was written to work with Fusebox, but it can be used with any code files. It's usually the first step I take when helping a new company implement Fusebox as it's easy to adopt and provides immediate benefits.

    The Fusedoc format I took out of one of my fuses is given in Listing 1. One of these goes at the top of every code file.

    Here's how to read the Fusedoc:

    <!-- actValidateUser.cfm -->

    The name of the fuse is set in an HTML comment, so if we do a "View Source" from within a browser, we can immediately tell what files are in play.

    <!--- || I make sure that the username and password given to me are valid entries in the USERS table. If they are, I will return to...

    This is the "Responsibilities" section of the Fusedoc. I write this in the first person (as if the fuse were speaking) and try to provide enough information for another person to tell immediately what's happening with the fuse. My goal is to provide enough for a CF coder, armed with a copy of the data schema, to write this fuse without any knowledge of the application in which it'll be used. The double pipe symbols (||) will be used by our "magic box" to extract individual pieces of the Fusedoc.

    || [email protected]

    You may want to keep historical information here about revisions, testing, etc.

    ||
    --> userName: a STRING
    --> password: a STRING
    --> RFA.successfulValidation: a valid FUSEACTION
    --> RFA.failedValidation: a valid FUSEACTION
    <-- [badlogin]: "yes"> <->
    ++> dsn: an APPLICATION variable ODBC datasource
    +++

    These are the various arguments being passed into and out of the fuse. There is a key to the meaning of the prefixes:

    --> an incoming parameter: the text following the prefix provides more information about the parameter
    --> [square brackets indicate that this incoming variable is optional]
    <-- an outgoing parameter
    <-- [same explanation as the square brackets above] <->

    a parameter that will be received by and sent from the fuse without being changed
    ++> a global variable not explicitly passed into the fuse, such as server, application and session variables
    +++ any file that is required by this fuse. This may include files, fusefunctions, etc.

    || FUSEDOC--->

    This just ends the Fusedoc section.

    I've found this system to be very workable; once used to it, programmers find it very helpful as it concisely communicates a good deal of information. Even pointy-haired managers and customers can look at the code and have a sense of what's going on.

    We can make it even more useful if we process this code through our "magic box" ­ a code file (fuseDocumentor.cfm) that parses the individual elements of the Fusedocs and outputs them on the screen. Fuse Documentor was written to be called as a custom tag. For parameters, it takesŠwell, let's just run the Fuse Documentor through itself to find out more about it (see Figure 1).

    If you want to see particulars on every file in a directory, you can write a little code that will loop through the directory and send each file to Fuse Documentor (see Listing 2). This will let you see very quickly what's going on in an entire code repository.

    Fusedoc is a small, lightweight system for seeing the structure of code. I've found it to be helpful in writing maintainable, reusable code. I hope you find it similarly helpful.

    You can download the Fuse Documentor file as well as a CF Studio template at www.TeamAllaire.com.

  • More Stories By Hal Helms

    Hal Helms is a well-known speaker/writer/strategist on software development issues. He holds training sessions on Java, ColdFusion, and software development processes. He authors a popular monthly newsletter series. For more information, contact him at hal (at) halhelms.com or see his website, www.halhelms.com.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    @ThingsExpo Stories
    "Cloud Academy is an enterprise training platform for the cloud, specifically public clouds. We offer guided learning experiences on AWS, Azure, Google Cloud and all the surrounding methodologies and technologies that you need to know and your teams need to know in order to leverage the full benefits of the cloud," explained Alex Brower, VP of Marketing at Cloud Academy, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clar...
    Large industrial manufacturing organizations are adopting the agile principles of cloud software companies. The industrial manufacturing development process has not scaled over time. Now that design CAD teams are geographically distributed, centralizing their work is key. With large multi-gigabyte projects, outdated tools have stifled industrial team agility, time-to-market milestones, and impacted P&L stakeholders.
    Gemini is Yahoo’s native and search advertising platform. To ensure the quality of a complex distributed system that spans multiple products and components and across various desktop websites and mobile app and web experiences – both Yahoo owned and operated and third-party syndication (supply), with complex interaction with more than a billion users and numerous advertisers globally (demand) – it becomes imperative to automate a set of end-to-end tests 24x7 to detect bugs and regression. In th...
    "Akvelon is a software development company and we also provide consultancy services to folks who are looking to scale or accelerate their engineering roadmaps," explained Jeremiah Mothersell, Marketing Manager at Akvelon, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    "MobiDev is a software development company and we do complex, custom software development for everybody from entrepreneurs to large enterprises," explained Alan Winters, U.S. Head of Business Development at MobiDev, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    SYS-CON Events announced today that CrowdReviews.com has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5–7, 2018, at the Javits Center in New York City, NY. CrowdReviews.com is a transparent online platform for determining which products and services are the best based on the opinion of the crowd. The crowd consists of Internet users that have experienced products and services first-hand and have an interest in letting other potential buye...
    "IBM is really all in on blockchain. We take a look at sort of the history of blockchain ledger technologies. It started out with bitcoin, Ethereum, and IBM evaluated these particular blockchain technologies and found they were anonymous and permissionless and that many companies were looking for permissioned blockchain," stated René Bostic, Technical VP of the IBM Cloud Unit in North America, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Conventi...
    SYS-CON Events announced today that Telecom Reseller has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5-7, 2018, at the Javits Center in New York, NY. Telecom Reseller reports on Unified Communications, UCaaS, BPaaS for enterprise and SMBs. They report extensively on both customer premises based solutions such as IP-PBX as well as cloud based and hosted platforms.
    "Space Monkey by Vivent Smart Home is a product that is a distributed cloud-based edge storage network. Vivent Smart Home, our parent company, is a smart home provider that places a lot of hard drives across homes in North America," explained JT Olds, Director of Engineering, and Brandon Crowfeather, Product Manager, at Vivint Smart Home, in this SYS-CON.tv interview at @ThingsExpo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    Coca-Cola’s Google powered digital signage system lays the groundwork for a more valuable connection between Coke and its customers. Digital signs pair software with high-resolution displays so that a message can be changed instantly based on what the operator wants to communicate or sell. In their Day 3 Keynote at 21st Cloud Expo, Greg Chambers, Global Group Director, Digital Innovation, Coca-Cola, and Vidya Nagarajan, a Senior Product Manager at Google, discussed how from store operations and ...
    In his session at 21st Cloud Expo, Carl J. Levine, Senior Technical Evangelist for NS1, will objectively discuss how DNS is used to solve Digital Transformation challenges in large SaaS applications, CDNs, AdTech platforms, and other demanding use cases. Carl J. Levine is the Senior Technical Evangelist for NS1. A veteran of the Internet Infrastructure space, he has over a decade of experience with startups, networking protocols and Internet infrastructure, combined with the unique ability to it...
    It is of utmost importance for the future success of WebRTC to ensure that interoperability is operational between web browsers and any WebRTC-compliant client. To be guaranteed as operational and effective, interoperability must be tested extensively by establishing WebRTC data and media connections between different web browsers running on different devices and operating systems. In his session at WebRTC Summit at @ThingsExpo, Dr. Alex Gouaillard, CEO and Founder of CoSMo Software, presented ...
    "There's plenty of bandwidth out there but it's never in the right place. So what Cedexis does is uses data to work out the best pathways to get data from the origin to the person who wants to get it," explained Simon Jones, Evangelist and Head of Marketing at Cedexis, in this SYS-CON.tv interview at 21st Cloud Expo, held Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA.
    WebRTC is great technology to build your own communication tools. It will be even more exciting experience it with advanced devices, such as a 360 Camera, 360 microphone, and a depth sensor camera. In his session at @ThingsExpo, Masashi Ganeko, a manager at INFOCOM Corporation, introduced two experimental projects from his team and what they learned from them. "Shotoku Tamago" uses the robot audition software HARK to track speakers in 360 video of a remote party. "Virtual Teleport" uses a multip...
    A strange thing is happening along the way to the Internet of Things, namely far too many devices to work with and manage. It has become clear that we'll need much higher efficiency user experiences that can allow us to more easily and scalably work with the thousands of devices that will soon be in each of our lives. Enter the conversational interface revolution, combining bots we can literally talk with, gesture to, and even direct with our thoughts, with embedded artificial intelligence, whic...
    SYS-CON Events announced today that Evatronix will exhibit at SYS-CON's 21st International Cloud Expo®, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Evatronix SA offers comprehensive solutions in the design and implementation of electronic systems, in CAD / CAM deployment, and also is a designer and manufacturer of advanced 3D scanners for professional applications.
    Leading companies, from the Global Fortune 500 to the smallest companies, are adopting hybrid cloud as the path to business advantage. Hybrid cloud depends on cloud services and on-premises infrastructure working in unison. Successful implementations require new levels of data mobility, enabled by an automated and seamless flow across on-premises and cloud resources. In his general session at 21st Cloud Expo, Greg Tevis, an IBM Storage Software Technical Strategist and Customer Solution Architec...
    To get the most out of their data, successful companies are not focusing on queries and data lakes, they are actively integrating analytics into their operations with a data-first application development approach. Real-time adjustments to improve revenues, reduce costs, or mitigate risk rely on applications that minimize latency on a variety of data sources. In his session at @BigDataExpo, Jack Norris, Senior Vice President, Data and Applications at MapR Technologies, reviewed best practices to ...
    An increasing number of companies are creating products that combine data with analytical capabilities. Running interactive queries on Big Data requires complex architectures to store and query data effectively, typically involving data streams, an choosing efficient file format/database and multiple independent systems that are tied together through custom-engineered pipelines. In his session at @BigDataExpo at @ThingsExpo, Tomer Levi, a senior software engineer at Intel’s Advanced Analytics gr...
    When talking IoT we often focus on the devices, the sensors, the hardware itself. The new smart appliances, the new smart or self-driving cars (which are amalgamations of many ‘things’). When we are looking at the world of IoT, we should take a step back, look at the big picture. What value are these devices providing? IoT is not about the devices, it’s about the data consumed and generated. The devices are tools, mechanisms, conduits. In his session at Internet of Things at Cloud Expo | DXWor...