Just my general comments about software documentation.

There are several types of engineering documentation. On the front end, the design document, or specification lays out the ideal that a development team hopes to attain. At the other end, manuals and online documentation help the user to understand and operate the product. Software developers have an in-between documentation stage that resides somewhere in the source code-notes that describe what is actually happening in the source code.

Since product development teams typically write their own specifications, they often start a design, write the design specification, and then go on to develop the product. Time and again, the documentation blahs bog down otherwise productive software developers. To a programmer, software development means writing code. That's the fun part-getting a program to do exactly what you want it to do. Documenting the code is the not-so-fun part, and it's often an afterthought. In many cases, the thought never even occurs! Perhaps the programmers burn out on documentation after writing the initial specification, and eagerly pursue a working product without leaving an adequate comment trail.

The best place to find undocumented source code is on the Internet. There are many sites that offer free code, but few have source-level documentation. Many of these software packages are from the open source community, and the documentation, both at the interface and implementation level, is inadequate. The definition for open source code does not state that the code must be documented, only readable. However, part of readability is in the code documentation! Some of the older and mature packages available have excellent documentation, and this is part of the reason these packages have succeeded. A case in point is Apache, the widely used HTTP server.

In chats, some open source developers, express the feeling that "you have to understand the technology in order to work with the source code." This is a fair statement. A programmer shouldn't hack around code that he doesn't understand. However, when programmers need to learn a technology, they reference source code that deals with the topic of interest. For some, this is part of the learning process. By not documenting code, the developer condemns the next programmer to reading an entire project, line by line, in order to understand what the application is supposed to do! This goes beyond the concept of understanding technology, and wastes a huge amount of time.

Another documentation dilemma is keeping internal and external documentation in synch. As an example, consider an API library. Typically, the API is documented in printed form. Information flows from developers to the documentation department. There, tech writers create a user's guide and a function guide that contains the API's functions, parameters and return codes. Keeping documentation current with an evolving API can be a burdensome task for all parties involved.

Today, tools that automatically pull documentation from the programmatic interface's source can solve this dilemma. These tools simply require the programmer to format comments such that the tools can identify and pull out the relevant information. For example, with Doxygen, the programmer creates an interface file, documents it, and then quickly creates a reference document for use or distribution. Of course, tools cannot automatically keep documentation in synch with actual code-but with good engineering practice, changes to the functional aspects of released modules that would invalidate the documentation can be strictly controlled. However, if something does change, and the developer notes this in the comments, voilà: the documentation tool can quickly create another set of documents that reflect the changes.

Now, documenting code really isn't that difficult. All it takes is self-discipline. I have found the following steps to be extremely helpful when writing code. This method scales very well: small and large projects benefit greatly. These steps are also language-independent.

1. Every source file should have a header at the top, which includes a definition of what the module is supposed to do. This keeps the developer focused on the task at hand.
2. Since the interface file should not change after the work is published, this is the safest place to document methods and parameters, and of course, any publicly visible variables included in the module.
3. Upon development of a method, before actually writing a line of code, it is useful to sit and roughly comment out the steps that are necessary to complete the function. Any thoughts about possibly difficult steps should be spelled out. Later, once all the steps that are necessary to write the function are complete, go back and fill in the blanks with the actual code. This keeps your code commented in blocks, rather than line-by-line. If a particular line is worrisome, then a programmer can make a special note regarding that line.

Comments

Add New Search

Write comment
Name:
Email:	do not notifynotify
Website:
Title:
UBBCode:	-color-aquablackbluefuchsiagraygreenlimemaroonnavyolivepurpleredsilvertealwhiteyellow -size-tinysmallmediumlargehuge

Powered by !JoomlaComment 3.12

Copyright (C) 2007 Alain Georgette / Copyright (C) 2006 Frantisek Hliva. All rights reserved.