Mac users' indifference toward security 'worrying' http://t.co/MBTwqilk
9 minutes ago by OnlineWebTips on twitter
Breaking News: Yahoo announces Alibaba stake sale
ZDNet / Techguide / Web Development
Different types of documentation for programmers
Summary
Justin James goes back to basics in this overview of the documentation types developers should know. Read about "self-documenting" code, UML and more.
Topics
justin james, xml, levit , technology, software engineering, software development, software, science and technology, computer technology, ibm corporation
Events
IBM Technology Conference & Expo 2012
May 22, 2012
One World Hotel, First Avenue, Bandar Utama City Centre, 47800 Petaling Jaya, Selangor
Echelon 2012
June 11 and 12, 2012
University Cultural Centre, National University of Singapore
Startup Asia Jakarta 2012
June 7 and 8, 2012
12th Floor, Annex Building, Wisma Nusantara Complex, Jl. M.H. Thamrin No. 59 Jakarta 10350, Indonesia
MMA Forum Singapore
April 23-25, 2012
Grand Hyatt Singapore
A new developer might be confused about which kinds of documentation are important, because we often use the very general term documentation rather than specifying the type. Here's a look at some of the types of documentation out there.
Code comments
When documentation is mentioned amongst developers, comments inserted directly into the source code are probably the most common understanding. This is especially true for recent graduates or newer programmers who encountered it in school, but never learned about more rigorous forms of documentation.
Comments have lost a lot of their utility over the years. Between the development of systems allowing longer, more descriptive variable names and development platforms and systems that allow for other kinds of documentation, comments no longer serve as the de facto documentation solution. That said, code comments still have value.
Code comments should not be used to replace descriptive variable names, though they are excellent for explaining the logic underlying a piece of code--not necessarily the how of a code block but the why. For example, a useful comment might be, "Spec says that a name must be three characters long and have only letters" to explain a piece of validation code. Comments become more useful when they directly refer to the specification, a bug, or other external documentation in an easy-to-reference way. "Fix for bug #598" or "Refer to change request A991" can go a long way in helping future maintainers understand the thinking behind an otherwise incomprehensible piece of code. Writing useful comments along these lines should become a habit if it isn't one already.
"Self-documenting" code
Thanks to systems that allow variable, class, and function names to be longer than they used to be, it is much easier to write "self-documenting" code; that is to say, the names of things convey their meaning without the need for inline comments. For example, a function such as "prfltocnsl" does not let the potential user know what it does as well as "PrintFloatToConsole". Like using inline comments wisely, this should become a standard practice for developers.
Generated API-style documentation
Some languages allow you to embed detailed documentation within the source code in a format (typically XML) that automated tools can use to generate packaged help. Some systems (like Visual Studio) can pick it up and use it in other ways too. This can be a really useful, but it is a lot of work to do something useful.
How many times have you seen the documentation for a ToString() method read something like, "Produces the string representation of the object." Gee, that was... uh... completely obvious, thanks. How about letting me know how that happens instead? For example, let's say you have a collection with a ToString() method. Instead of forcing the developer to guess what the output will look like, the documentation should provide an example of what a sample instance looks like when ToString() is called. Likewise, too many times the "examples" just show the obvious syntax in a basic "hello world" context without explaining how or why you would really do any of this.
Bug tracker, task list, or project management system
There has been an explosion in tools that allow teams to enter bugs, tasks, to-do lists, and so on. The tools allow items to be tracked very granularly, and for the user to assign gobs of metadata to any given item. With this metadata, managers can do things like make graphs, charts, and reports showing a ton of different stats, like average bug resolution time or the number of features implemented per developer. Some of these systems can tie into your source code system, so that you can easily view code check-ins in the context of the tasks they addressed (this is a very handy feature).
While the stats that can be pulled are often of dubious relevance towards evaluating quality or productivity, these systems have lots of value. Being able to rapidly find and mine common bugs, change requests, and so on is a big help. It's also nice to not have to wade through endless piles of separate pieces of paper, emails, or files trying to figure out where someone stuck that change request so you can figure out why you spent three weeks making a change that everyone seems to hate.
UML
UML is a special file format design for documenting applications. UML can be consumed by a variety of tools to produce documents, database diagrams, process flowcharts, and more. Even better, some tools can take UML and stub out applications and databases based upon it.
UML is particularly prevalent in the Java ecosystem, thanks to the Rational Suite of tools that IBM owns. UML seems to be considered an enterprise development tool, due to the learning curve and cost of the tools associated with it.
Ad-hoc documents
This style of documentation is sadly too prevalent. With ad-hoc documentation, you usually lack version control. It's also difficult to search and, worst of all, you tend to get multiple copies of the documents with differences floating all over the place.
There are some uses for these kinds of files, but they work a lot better if they are participating in a more rigorous documentation system, such as attached to a bug ticket or change request.
Justin James is an employee of Levit & James, Inc. in a multidisciplinary role that combines programming, network management, and system administration. He has been blogging at TechRepublic since 2005.
Resource Centre Useful content from our premier sponsors
Web Development TechGuides
Creating a liquid layout for an Agile Platform theme
Working with Visual Studio 2010 from command line
Key to making applications discoverable
Easily connect to RavenDB data via C#
Use qTrace to replicate errors for QA testing
Tips on making sure your apps work for mobile users
RavenDB, a database alternative for .NET developers
Importing existing database schemas as Agile Platform entities
5 persistent Web application myths
Improve page performance with Microsoft Ajax Minifier
ZDNet Asia Live
RT @Bilafer: 25% of top VC firms investing in China, India or both. Good news for innovation, #SAPAPJ http://t.co/wkCXKkxU
9 minutes ago by businessobjects on twitter
Mac users' indifference toward security 'worrying' http://t.co/AkSlHrCH #cyber #infosec
9 minutes ago by Sec_Cyber on twitter
RT @zdnetasia: Gartner: Mobile CRM gives better ROI than social. http://t.co/nTgj44H8
39 minutes ago by Oystor_Tweets on twitter
China hits back at Pentagon report on spy claims. http://t.co/CccR4SBM
39 minutes ago by zdnetasia on twitter
China hits back at Pentagon report on spy claims http://t.co/YP380BYQ http://t.co/erFX4aVv #arcavir
39 minutes ago by V_RaV on twitter
http://t.co/VNaZtseV China hits back at Pentagon report on spy claims: Annual report by Pent... http://t.co/TvgCi5RE http://t.co/wiqY9ktt
39 minutes ago by RavtachSolution on twitter
#AntiVirus News: Mac users' indifference toward security 'worrying' http://t.co/spWS0CpU #AdAware
39 minutes ago by AdAwareFree on twitter
Mac users' indifference toward security 'worrying' http://t.co/BtVn1BAk
> expected! They still remember Mac vs PC ads
#infosec #news #apple
Pentagon report says China exploit US tech, conduct cyberespionage, China says it has been "unjustly criticized" http://t.co/P5wgqy6I #in
54 minutes ago by EllyZDNetAsia on twitter
Mac users' indifference toward security 'worrying': 59 Jakarta 10350, Indonesia In light of the recent spate of ... http://t.co/Lxgnc1wM
1 hour ago by GoodCodeBadCode on twitter
Pakistan lifts block on Twitter - ZDNet Asia: Pakistan lifts block on TwitterZDNet Asia59 Jakarta 10350, Indones... http://t.co/61n85ajh
1 hour ago by semarang_photo on twitter
Pakistan lifts block on Twitter http://t.co/WHqoJOqm http://t.co/erFX4aVv #arcavir
1 hour ago by V_RaV on twitter
http://t.co/VNaZtseV Pakistan lifts block on Twitter: Country restores access after briefly ... http://t.co/5gqegFWK http://t.co/wiqY9ktt
1 hour ago by RavtachSolution on twitterI reckon your view: "CRM is strategy, not software", if a company replicating the approach uses in ERP implementation into CRM, what they...
3 hours ago by wykoong on Gartner: Mobile CRM gives better ROI than socialThis video will teach you about the Excel fill handle but also provide you with a workook to download... http://www.youtube.com/watch?v=...
20 hours ago by TradeBrother on A quick fill handle trick for Microsoft Excelwaiting...
2 days ago by eapete on What should count in a company's market value?Boy, you've opened a can of worms now.
Wait for the rants & raves.
I was puzzling before this whether to replicate the success formula we executed for a financial institute, and come out with a standard s...
3 days ago by wykoong on Drop the egos, copy ideas, then innovateKeep up with ZDNet Asia
Facebook 
RSS Feeds 
Newsletters 
Twitter Whitepapers
Downloads
Web Development News
Inside ZDNet Asia
Sponsored
Echelon 2012 - The Awesomer Tech Event in Asia
Echelon 2012 – SEA’s longest running tech startup event goes Awesomer. Catch 50 of Asia’s most promising startups & over 40 international speakers on June 11-12.
Startup Asia Jakarta showcases new product-ready tech startups. Plus: hackathon, exhibition, and speakers. Use promo code CBSi50 for 50% discount.
ZDNet Asia Intelligent Singapore video series
Featuring inteviews with CXOs who define "intelligence" in their markets and reveal how their companies drive business efficiencies through ICT.
