Click here to close now.




















Welcome!

You will be redirected in 30 seconds or close now.

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

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 IceWarp will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. IceWarp, the leader of cloud and on-premise messaging, delivers secured email, chat, documents, conferencing and collaboration to today's mobile workforce, all in one unified interface
    In his session at @ThingsExpo, Lee Williams, a producer of the first smartphones and tablets, will talk about how he is now applying his experience in mobile technology to the design and development of the next generation of Environmental and Sustainability Services at ETwater. He will explain how M2M controllers work through wirelessly connected remote controls; and specifically delve into a retrofit option that reverse-engineers control codes of existing conventional controller systems so they don't have to be replaced and are instantly converted to become smart, connected devices.
    The Internet of Things is in the early stages of mainstream deployment but it promises to unlock value and rapidly transform how organizations manage, operationalize, and monetize their assets. IoT is a complex structure of hardware, sensors, applications, analytics and devices that need to be able to communicate geographically and across all functions. Once the data is collected from numerous endpoints, the challenge then becomes converting it into actionable insight.
    With the proliferation of connected devices underpinning new Internet of Things systems, Brandon Schulz, Director of Luxoft IoT – Retail, will be looking at the transformation of the retail customer experience in brick and mortar stores in his session at @ThingsExpo. Questions he will address include: Will beacons drop to the wayside like QR codes, or be a proximity-based profit driver? How will the customer experience change in stores of all types when everything can be instrumented and analyzed? As an area of investment, how might a retail company move towards an innovation methodolo...
    SYS-CON Events announced today that HPM Networks will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. For 20 years, HPM Networks has been integrating technology solutions that solve complex business challenges. HPM Networks has designed solutions for both SMB and enterprise customers throughout the San Francisco Bay Area.
    Consumer IoT applications provide data about the user that just doesn’t exist in traditional PC or mobile web applications. This rich data, or “context,” enables the highly personalized consumer experiences that characterize many consumer IoT apps. This same data is also providing brands with unprecedented insight into how their connected products are being used, while, at the same time, powering highly targeted engagement and marketing opportunities. In his session at @ThingsExpo, Nathan Treloar, President and COO of Bebaio, will explore examples of brands transforming their businesses by t...
    Through WebRTC, audio and video communications are being embedded more easily than ever into applications, helping carriers, enterprises and independent software vendors deliver greater functionality to their end users. With today’s business world increasingly focused on outcomes, users’ growing calls for ease of use, and businesses craving smarter, tighter integration, what’s the next step in delivering a richer, more immersive experience? That richer, more fully integrated experience comes about through a Communications Platform as a Service which allows for messaging, screen sharing, video...
    SYS-CON Events announced today that Pythian, a global IT services company specializing in helping companies leverage disruptive technologies to optimize revenue-generating systems, has been named “Bronze Sponsor” of SYS-CON's 17th Cloud Expo, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Founded in 1997, Pythian is a global IT services company that helps companies compete by adopting disruptive technologies such as cloud, Big Data, advanced analytics, and DevOps to advance innovation and increase agility. Specializing in designing, imple...
    As more and more data is generated from a variety of connected devices, the need to get insights from this data and predict future behavior and trends is increasingly essential for businesses. Real-time stream processing is needed in a variety of different industries such as Manufacturing, Oil and Gas, Automobile, Finance, Online Retail, Smart Grids, and Healthcare. Azure Stream Analytics is a fully managed distributed stream computation service that provides low latency, scalable processing of streaming data in the cloud with an enterprise grade SLA. It features built-in integration with Azur...
    SYS-CON Events announced today that Micron Technology, Inc., a global leader in advanced semiconductor systems, will exhibit at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA. Micron’s broad portfolio of high-performance memory technologies – including DRAM, NAND and NOR Flash – is the basis for solid state drives, modules, multichip packages and other system solutions. Backed by more than 35 years of technology leadership, Micron's memory solutions enable the world's most innovative computing, consumer,...
    Contrary to mainstream media attention, the multiple possibilities of how consumer IoT will transform our everyday lives aren’t the only angle of this headline-gaining trend. There’s a huge opportunity for “industrial IoT” and “Smart Cities” to impact the world in the same capacity – especially during critical situations. For example, a community water dam that needs to release water can leverage embedded critical communications logic to alert the appropriate individuals, on the right device, as soon as they are needed to take action.
    While many app developers are comfortable building apps for the smartphone, there is a whole new world out there. In his session at @ThingsExpo, Narayan Sainaney, Co-founder and CTO of Mojio, will discuss how the business case for connected car apps is growing and, with open platform companies having already done the heavy lifting, there really is no barrier to entry.
    With the Apple Watch making its way onto wrists all over the world, it’s only a matter of time before it becomes a staple in the workplace. In fact, Forrester reported that 68 percent of technology and business decision-makers characterize wearables as a top priority for 2015. Recognizing their business value early on, FinancialForce.com was the first to bring ERP to wearables, helping streamline communication across front and back office functions. In his session at @ThingsExpo, Kevin Roberts, GM of Platform at FinancialForce.com, will discuss the value of business applications on wearable ...
    As more intelligent IoT applications shift into gear, they’re merging into the ever-increasing traffic flow of the Internet. It won’t be long before we experience bottlenecks, as IoT traffic peaks during rush hours. Organizations that are unprepared will find themselves by the side of the road unable to cross back into the fast lane. As billions of new devices begin to communicate and exchange data – will your infrastructure be scalable enough to handle this new interconnected world?
    WebRTC has had a real tough three or four years, and so have those working with it. Only a few short years ago, the development world were excited about WebRTC and proclaiming how awesome it was. You might have played with the technology a couple of years ago, only to find the extra infrastructure requirements were painful to implement and poorly documented. This probably left a bitter taste in your mouth, especially when things went wrong.
    Too often with compelling new technologies market participants become overly enamored with that attractiveness of the technology and neglect underlying business drivers. This tendency, what some call the “newest shiny object syndrome,” is understandable given that virtually all of us are heavily engaged in technology. But it is also mistaken. Without concrete business cases driving its deployment, IoT, like many other technologies before it, will fade into obscurity.
    The Internet of Things (IoT) is about the digitization of physical assets including sensors, devices, machines, gateways, and the network. It creates possibilities for significant value creation and new revenue generating business models via data democratization and ubiquitous analytics across IoT networks. The explosion of data in all forms in IoT requires a more robust and broader lens in order to enable smarter timely actions and better outcomes. Business operations become the key driver of IoT applications and projects. Business operations, IT, and data scientists need advanced analytics t...
    Akana has announced the availability of the new Akana Healthcare Solution. The API-driven solution helps healthcare organizations accelerate their transition to being secure, digitally interoperable businesses. It leverages the Health Level Seven International Fast Healthcare Interoperability Resources (HL7 FHIR) standard to enable broader business use of medical data. Akana developed the Healthcare Solution in response to healthcare businesses that want to increase electronic, multi-device access to health records while reducing operating costs and complying with government regulations.
    For IoT to grow as quickly as analyst firms’ project, a lot is going to fall on developers to quickly bring applications to market. But the lack of a standard development platform threatens to slow growth and make application development more time consuming and costly, much like we’ve seen in the mobile space. In his session at @ThingsExpo, Mike Weiner, Product Manager of the Omega DevCloud with KORE Telematics Inc., discussed the evolving requirements for developers as IoT matures and conducted a live demonstration of how quickly application development can happen when the need to comply wit...
    The Internet of Everything (IoE) brings together people, process, data and things to make networked connections more relevant and valuable than ever before – transforming information into knowledge and knowledge into wisdom. IoE creates new capabilities, richer experiences, and unprecedented opportunities to improve business and government operations, decision making and mission support capabilities.