> -----Original Message----- > From: Mike Tangorre [mailto:[EMAIL PROTECTED] > Sent: Friday, January 26, 2007 12:47 PM > To: CF-Community > Subject: Source Code Documentation > > Ok, how many of you adequately document your source code? By adequately I > mean to a point where another developer can jump into an application and > be > productive in a short period of time. > > Also, if time is tight on a project, how many feel source code > documentation > is the first place that takes a hit?
I try to always document fully... but it rarely works out. It's worth it to spend some time and work out a system (or adopt one) for self-documentation. Although it's getting pretty old I'm still happy with my self-documentation library for CFCs. All of the "Component Catalogs" list here are self-documenting: http://www.depressedpress.com/Content/Development/ColdFusion/DPLibraries/ The component that does the work is here (very long URL): http://www.depressedpress.com/Content/Development/ColdFusion/DPLibraries/Doc umentation/DocViewer.cfm?Component=cfc_DepressedPress.Utility.DP_Documentati on The component looks for special "<dpDoc>" tags within the code that extend the normal CFC introspection capabilities. dpDocs can define future plans, revisions, meta information, return information and so forth. It does take longer to write CFC's at the beginning, but not much longer than it does to comment in the first place (especially if you work from a template). Lacking a system like that (which I lack, for example, for JavaScript) I try to make my comments as regular as possible: standardized spacers and headers for groups of methods, etc. I also find it useful to "negatively comment" - even when there's no explanatory need to comment, for example a method return, I always do. Just saying "// Return nothing" isn't that useful in-and-of itself, but it does show that you considered this return just as you did the others - you're saying "no suprises here". Lastly I always try and create "Steady State" documentation. This is hardest to get time for (comments and introspective documentation can be slipped into the development work, this can't). This includes functional and technical specifications detailing every aspect of the system/application/component, technologies used, decisions or assumptions made, etc. This kind of documentation can be heavy, long and dull and, for it to be truly useful, needs to be maintained and updated EVERY TIME the system is - but it can also be amazingly useful. NOT having steady-state documentation for a system, even a relatively simple one, means that every maintenance project has to start with a (generally unofficial) "what the hell does this thing do right now?" project phrase. Changes are made according to the current developer's time and budget rather than an overarching technical strategy. In my experience at least the lack of this documentation results in what I like to call "Accelerated Maintenance": the more changes are made to a project the longer ANY change takes until you're spending more time trying to figure out the "what they hell" questions than actually improving it. In case you can't guess I am personally on several projects in this state right now. ;^) Jim Davis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Upgrade to Adobe ColdFusion MX7 Experience Flex 2 & MX7 integration & create powerful cross-platform RIAs http:http://ad.doubleclick.net/clk;56760587;14748456;a?http://www.adobe.com/products/coldfusion/flex2/?sdid=LVNU Archive: http://www.houseoffusion.com/groups/CF-Community/message.cfm/messageid:225929 Subscription: http://www.houseoffusion.com/groups/CF-Community/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.5
