Okay, so we all know that documentation is important.? We've all seen the different methodologies and catchphrases that try to promote documentation... "code your documentation, don't document your code", yadda yadda.? Yet somehow good documentation is still so very hard to come by.? Sometimes it's never even a thought.? Often, it's considered and dismissed -- "This app is so small, and this code is so obvious... I don't need to write any separate documentation."? Sometimes an attempt is made, a good first draft is created, and then it lingers in limbo while the app is developed, then moved to beta, then released... and then the questions flow in like water over Niagra Falls. "Process X doesn't act anything like the documentation said it would!? What am I doing wrong?"

For companies that publish APIs, their job has to be tough.? They not only have to document their API, but they are often expected to provide code examples for pretty much every platform that can consume a web service.? (With ColdFusion examples almost always an afterthought, provided by a third party after the API is published?)? Providing example code that covers the broad spectrum of platforms is surely a daunting task, but in my opinion it's a necessary evil if you want people to use your API, and therefore find value in your service -- and by association, your company.

On three separate occasions now, I've been tasked with consuming a web service using ColdFusion, and encountered either poor documentation, or example code that does not include ColdFusion, or -- worst of all, as the case was this past week -- sample ColdFusion code that was flat-out wrong, but promoted by the web service provider as being "working code".

This last example of "documentation" -- untested code examples that are just assumed to be working -- is almost worse than no documentation at all.? It sends you immediately down the wrong path.? Your XML can be 100% valid, your server SSL certificates can be properly imported, your network connectivity can be perfect, your implementation of the sample code can be near-verbatim... and still nothing works.? You look in all the wrong areas, because the assumption is that the "working example" actually works.? You review it when you receive it, you determine "this looks like it makes total sense", and then you rarely, if ever, question it until you've exhausted all other possibilities... sometimes hours later.

Are we all guilty of poor or non-existent documentation?? I'm sure we are.? At one time or another, we've all been pressed for time, and kicked out code (good code) but without docs.? And some of us I'm sure have even provided untested "example" code to someone(s), without really thinking about how time consuming such "helpful" code can be.? I'm embarassed to think of the poor or non-existent documentation I've created.?? I'm pretty sure I've never passed on "broken working code", but only because I know how unhelpful it really is.? If someone else is going to use my code, I take on a whole extra persona -- the code and related documentation are suddenly more polished, accurate, "beautiful".? But should it always be that way??

A good friend of mine conveyed this simple axiom, which has stuck with me ever since I first heard it:

"In the software world, the difference between an amateur and a professional is Documentation."

I submit here an extension to this axiom -- That it's not just by creating documentation that you are a professional... but also that by taking the extra time for documentation, you become a professional.? Through your documentation, your output across the board becomes professional grade.

I believe in this, and nowadays my projects take a little longer because I don't just write the code, but I also take at least some extra time to document what I've written.? Usually at the method (function) level, at the very least, if there's not going to be a formal Help system or actual book.

What I discovered, that I would pass on to anyone new to coding, is that when I write a function to completion (and when tested, it works) and then take the time (REAL time) to review it and add Hint or Description attributes to the CFFUNCTION and CFARGUMENT tags, perhaps refactor some variable names so it's more clear what they are holding (with the requisite re-testing to make sure I didn't just break it), I end up either making the function more efficient, the code more clear, or in some cases, even fixing what would have been a potential logic error.? My understanding of the code comes in line with the code itself, AND VICE VERSA.

The more complex the function, the more comments end up in the HINT/DESCRIPTION attributes or in separate comment blocks... in the function or in the test for it.? It's not full-blown documentation, but it often leaves a solid foundation upon which a good book could be written.

Further to the cause, I often use the TYPE attribute on my cfarguments, even though in production we turn off type checking, and checking for Type is just silly in CF because it's a dynamically typed language anyway.? I was asked once, "Why do you do that?? You know darn well it's never going to get used."

But it does.? By me.? It's my documentation... it says "This function takes this argument, and this argument is expected to be of this Type."? If the type could be Any, then I make sure the code says "type='any'".? (But, I can't remember the last time I used "Any".)

Is this redundant? Perhaps. But when I run through my code with cfcdoc, and it pulls all that information into one JavaDoc-style document, it provides that little extra bit of verification and documentation about my code.? It also provides another clue as to what I was thinking at the time I wrote the function.

So I use HINT, DESCRIPTION and TYPE not because they have a direct effect in the code, but rather, a direct effect on my Future Self -- the guy who 6 days or 6 years from now is pawing through the code, looking for a bug or to make modifications.? I'm doing Future Self a big favor -- I picture him sitting in this same spot (hopefully he's purchased a more comfortable chair by then!), looking over the code and saying a "thank you" to me for clarifying my understanding of the code, IN the code, at inception.

Used to be, only my "example code" for others would posess this extra attention.? And it was rare that I was providing example code to anyone, so it was rare that I was being as diligent as I am today.? But eventually, I got tired of Future Self being so frustrated with Present Self over unclear code and functionality.

My point in all this?? I guess it would be:

1.? To propose that you don't spin your wheels too long before you decide to second-guess and dig deep into what was once considered "working example code".? It's possible that someone took some Actual Working Code, copy/pasted it, and removed or changed something that was specific to their use of it in an attempt to make it "generic" for reuse, bunged it up in the process, and never actually tested it.?? Then they "helpfully" passed that code abortion on to you.? (or in the case of this week's experience, they passed it back to the web service provider as "working", which the provider would later pass on to me to try and make work... because they were too lazy or didn't have the time or resources to actually create a working example in-house for their API, for the ColdFusion platform);

1a.? Give back, if you have time.? If you received bad "advice" from a "working code example", and you have the time... help out that API provider by taking extra time to genericize your WORKING solution, document it, and hand it back to them.? Tell them what's different about your code, why it's better (or why it works at all, compared to what they gave you), and give them permission to pass it on to future clients.? Just make sure (please!) that you fully test what you're giving back, to the best of your time and ability.? Your donation will most certainly help others, and those that are providing the API might very well be more flexible with you in the future...? who knows -- your "gift" could even lead to more work (the kind that actually pays) in the future.

2.? To propose using attributes like HINT or DESCRIPTION or TYPE using clear language that a much lower-level developer would understand, and/or with the idea that it's going to be consolidated into one working API document (even if it never will);

3.? To propose that you take that extra 10 or 15 minutes to more fully document your function, the moment you consider it "done".? That extra time "summarizing" in the code, and in your own head, could lead to a refactoring of your function that makes it better, or eliminates a logic error, or at the very least, creates a nice little nugget of info for Future Self to work with, and thank you for.? While it's great when other people compliment you, to me it's 10x more rewarding when I find Future Self complimenting Present Self... in this case, for some time or frustration saved.

4.? To initiate a conversation about how someone in my position -- a lone CF developer with very little time on his hands -- can at least attempt to provide some reasonable documentation for his code.? So, how about it?? What are YOU doing to document your code, and/or prevent passing off broken "working code" to someone else?

Thanks for reading!

?