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
    SYS-CON Events announced today that TidalScale, a leading provider of systems and services, 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. TidalScale has been involved in shaping the computing landscape. They've designed, developed and deployed some of the most important and successful systems and services in the history of the computing industry - internet, Ethernet, operating s...
    SYS-CON Events announced today that Massive Networks, that helps your business operate seamlessly with fast, reliable, and secure internet and network solutions, has been named "Exhibitor" of 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. As a premier telecommunications provider, Massive Networks is headquartered out of Louisville, Colorado. With years of experience under their belt, their team of...
    SYS-CON Events announced today that IBM has been named “Diamond Sponsor” of SYS-CON's 21st Cloud Expo, which will take place on October 31 through November 2nd 2017 at the Santa Clara Convention Center in Santa Clara, California.
    Infoblox delivers Actionable Network Intelligence to enterprise, government, and service provider customers around the world. They are the industry leader in DNS, DHCP, and IP address management, the category known as DDI. We empower thousands of organizations to control and secure their networks from the core-enabling them to increase efficiency and visibility, improve customer service, and meet compliance requirements.
    SYS-CON Events announced today that TidalScale 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. TidalScale is the leading provider of Software-Defined Servers that bring flexibility to modern data centers by right-sizing servers on the fly to fit any data set or workload. TidalScale’s award-winning inverse hypervisor technology combines multiple commodity servers (including their ass...
    As hybrid cloud becomes the de-facto standard mode of operation for most enterprises, new challenges arise on how to efficiently and economically share data across environments. In his session at 21st Cloud Expo, Dr. Allon Cohen, VP of Product at Elastifile, will explore new techniques and best practices that help enterprise IT benefit from the advantages of hybrid cloud environments by enabling data availability for both legacy enterprise and cloud-native mission critical applications. By rev...
    Join IBM November 1 at 21st Cloud Expo at the Santa Clara Convention Center in Santa Clara, CA, and learn how IBM Watson can bring cognitive services and AI to intelligent, unmanned systems. Cognitive analysis impacts today’s systems with unparalleled ability that were previously available only to manned, back-end operations. Thanks to cloud processing, IBM Watson can bring cognitive services and AI to intelligent, unmanned systems. Imagine a robot vacuum that becomes your personal assistant tha...
    As popularity of the smart home is growing and continues to go mainstream, technological factors play a greater role. The IoT protocol houses the interoperability battery consumption, security, and configuration of a smart home device, and it can be difficult for companies to choose the right kind for their product. For both DIY and professionally installed smart homes, developers need to consider each of these elements for their product to be successful in the market and current smart homes.
    In his Opening Keynote at 21st Cloud Expo, John Considine, General Manager of IBM Cloud Infrastructure, will lead you through the exciting evolution of the cloud. He'll look at this major disruption from the perspective of technology, business models, and what this means for enterprises of all sizes. John Considine is General Manager of Cloud Infrastructure Services at IBM. In that role he is responsible for leading IBM’s public cloud infrastructure including strategy, development, and offering ...
    SYS-CON Events announced today that N3N will exhibit at SYS-CON's @ThingsExpo, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. N3N’s solutions increase the effectiveness of operations and control centers, increase the value of IoT investments, and facilitate real-time operational decision making. N3N enables operations teams with a four dimensional digital “big board” that consolidates real-time live video feeds alongside IoT sensor data a...
    In a recent survey, Sumo Logic surveyed 1,500 customers who employ cloud services such as Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). According to the survey, a quarter of the respondents have already deployed Docker containers and nearly as many (23 percent) are employing the AWS Lambda serverless computing framework. It’s clear: serverless is here to stay. The adoption does come with some needed changes, within both application development and operations. Tha...
    SYS-CON Events announced today that Avere Systems, a leading provider of enterprise storage for the hybrid cloud, 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. Avere delivers a more modern architectural approach to storage that doesn't require the overprovisioning of storage capacity to achieve performance, overspending on expensive storage media for inactive data or the overbui...
    With major technology companies and startups seriously embracing Cloud strategies, now is the perfect time to attend 21st Cloud Expo October 31 - November 2, 2017, at the Santa Clara Convention Center, CA, and June 12-14, 2018, at the Javits Center in New York City, NY, and learn what is going on, contribute to the discussions, and ensure that your enterprise is on the right path to Digital Transformation.
    SYS-CON Events announced today that mruby Forum will exhibit at the Japan External Trade Organization (JETRO) Pavilion 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. mruby is the lightweight implementation of the Ruby language. We introduce mruby and the mruby IoT framework that enhances development productivity. For more information, visit http://forum.mruby.org/.
    Digital transformation is changing the face of business. The IDC predicts that enterprises will commit to a massive new scale of digital transformation, to stake out leadership positions in the "digital transformation economy." Accordingly, attendees at the upcoming Cloud Expo | @ThingsExpo at the Santa Clara Convention Center in Santa Clara, CA, Oct 31-Nov 2, will find fresh new content in a new track called Enterprise Cloud & Digital Transformation.
    Amazon is pursuing new markets and disrupting industries at an incredible pace. Almost every industry seems to be in its crosshairs. Companies and industries that once thought they were safe are now worried about being “Amazoned.”. The new watch word should be “Be afraid. Be very afraid.” In his session 21st Cloud Expo, Chris Kocher, a co-founder of Grey Heron, will address questions such as: What new areas is Amazon disrupting? How are they doing this? Where are they likely to go? What are th...
    Most technology leaders, contemporary and from the hardware era, are reshaping their businesses to do software. They hope to capture value from emerging technologies such as IoT, SDN, and AI. Ultimately, irrespective of the vertical, it is about deriving value from independent software applications participating in an ecosystem as one comprehensive solution. In his session at @ThingsExpo, Kausik Sridhar, founder and CTO of Pulzze Systems, will discuss how given the magnitude of today's applicati...
    SYS-CON Events announced today that NetApp has been named “Bronze Sponsor” of 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. NetApp is the data authority for hybrid cloud. NetApp provides a full range of hybrid cloud data services that simplify management of applications and data across cloud and on-premises environments to accelerate digital transformation. Together with their partners, NetApp emp...
    Smart cities have the potential to change our lives at so many levels for citizens: less pollution, reduced parking obstacles, better health, education and more energy savings. Real-time data streaming and the Internet of Things (IoT) possess the power to turn this vision into a reality. However, most organizations today are building their data infrastructure to focus solely on addressing immediate business needs vs. a platform capable of quickly adapting emerging technologies to address future ...
    SYS-CON Events announced today that SkyScale 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. SkyScale is a world-class provider of cloud-based, ultra-fast multi-GPU hardware platforms for lease to customers desiring the fastest performance available as a service anywhere in the world. SkyScale builds, configures, and manages dedicated systems strategically located in maximum-security...