Friday, April 21, 2006
Help fellow developers by writing useful documentation
By Tony Patton , TechRepublic
12 Apr 2006
Every developer knows what it's like to have to make changes to an existing application. It is the true test of a developer's skills to reverse engineer a previous team's thinking. One thing that can really hinder this process is when there's no documentation and all the developers involved with the application are no longer around.
So, if developers are aware that even basic documentation can be helpful, why do we often overlook this task? Most developers I know admit that they just don't have enough time to write documentation. However, this mundane task can actually save you or your fellow developers time down the road.
If you need to write documentation, check out my tips on what it should include and where to find tools that will assist you in this process.
Describe an application's core elements
It can be a bit overwhelming to start composing a document that outlines the technical details of an application. One way to make the process less daunting is by first looking at the four core elements that are in every application: data, business rules, user interface, and security. Here are more details about each element:
* Data: The backend data utilized by a system can be as simple as a few tables or as complex hundreds of tables as well as stored procedures, views, and so forth. An up-to-date data model/diagram can save hours of time when faced with a new system.
* Business rules: Current approaches to system design place business rules in their own objects, which are separate from the data and the user interface, but this isn't often the case. A simple document outlining a system's business rules can greatly enhance the understanding of what an application actually does.
* User interface: I think the user interface is one of the easier application features to understand, primarily because you get a good feel for it by simply loading and using the application. Custom controls or third-party tools are often used, so the learning curve is often steeper. A good approach to documenting the user interface is to provide a list of the forms and other elements utilized in the system, along with a detailed description of each.
* Security: Developers often overlook this feature when documenting a system. As you browse through existing code, you'll undoubtedly notice security checks applied in various areas, but it is hard to grasp an overall understanding of an application's security model.
Enhance documentation with pictures
It's easy to enhance the four core elements with diagrams and figures. Database systems like SQL Server make it easy to churn out a data model via the Diagrams element within the SQL Server Enterprise Management client. The Diagrams feature assumes the database was properly designed (primary and foreign key relationships) so it can properly identify relationships. If primary and foreign keys are not appropriately defined, relationships are apparent between the elements, thus making it hard for the system to generate a helpful diagram. You should use a tool like Visio or your favorite word processor to create diagrams for your system as you build it.
Screen captures are a great way to document the user interface and provide an overview of a page. You should annotate screen captures to point out various functions. Tools like AnyDoc Software's CAPTUREit simplify the process of grabbing and working with screen captures.
Unified Modeling Language (UML) has evolved into the standard for describing a system with its various diagrams and symbols. UML diagrams include: architecture, sequence, and class.
* An architecture diagram describes the overall system, detailing the various layers of the system and how different users interface with them as well as business rules.
* You can use sequence diagrams to document processes.
* Class diagrams outline system objects.
While IBM Rational provides powerful (and expensive) UML tools, you can create UML diagrams using other products such as Visio.
Insert comments in your code
The most basic form of documentation is code comments. The .NET Framework uses the Java approach to using XML style comments in C#. Then, a developer can use a command-line tool to extract these comments and create basic system documentation of code elements. If the developer properly inserts comments in the code, it's possible to extract object relationships from the comments.
While it's ideal to insert comments as you develop, it can also be useful to insert comments when you make changes to the code, in order to let other developers know what you change and why. These comments are particularly useful for resolving problems that occur after a code change (source control can also address that problem).
Check out these commercial tools
Compiling your own document can be time-consuming. There are various commercial products available to automate the process of documenting your code. Here are two I recommend:
* ASP.NET Documentation Tool: Offers rudimentary code documentation by providing a simple snapshot of all code elements from the source. Similar items like forms, controls, and such are grouped together. (A similar tool is available for SQL Server.)
* PrettyCode.Print for .NET: Provides an easy way to generate hard copies of source code that are readable. The output is formatted with line numbers and so forth.
These tools simply spit out existing code and comments in a readable format. They don't (and cannot) insert any comments on the "how and why" questions developers usually hear when they're examining an application.
Other resources
Microsoft's patterns & practices site has a great book on building secure ASP.NET applications. It includes various security model diagrams that you may use as a starting point for documenting your own system.
You should also check at your favorite bookseller for books focusing on technical documentation and UML. There is plenty of information available for those wanting to know more.
Think of your fellow developer
I feel obligated to create documentation when I think of how much my effort will help another developer do his or her job. Even if you don't have time to create as detailed documentation as you would like, a simple document explaining what the system is supposed to do and why it was built can go a long way in helping to answer questions and resolve problems in the future.
Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.
12 Apr 2006
Every developer knows what it's like to have to make changes to an existing application. It is the true test of a developer's skills to reverse engineer a previous team's thinking. One thing that can really hinder this process is when there's no documentation and all the developers involved with the application are no longer around.
So, if developers are aware that even basic documentation can be helpful, why do we often overlook this task? Most developers I know admit that they just don't have enough time to write documentation. However, this mundane task can actually save you or your fellow developers time down the road.
If you need to write documentation, check out my tips on what it should include and where to find tools that will assist you in this process.
Describe an application's core elements
It can be a bit overwhelming to start composing a document that outlines the technical details of an application. One way to make the process less daunting is by first looking at the four core elements that are in every application: data, business rules, user interface, and security. Here are more details about each element:
* Data: The backend data utilized by a system can be as simple as a few tables or as complex hundreds of tables as well as stored procedures, views, and so forth. An up-to-date data model/diagram can save hours of time when faced with a new system.
* Business rules: Current approaches to system design place business rules in their own objects, which are separate from the data and the user interface, but this isn't often the case. A simple document outlining a system's business rules can greatly enhance the understanding of what an application actually does.
* User interface: I think the user interface is one of the easier application features to understand, primarily because you get a good feel for it by simply loading and using the application. Custom controls or third-party tools are often used, so the learning curve is often steeper. A good approach to documenting the user interface is to provide a list of the forms and other elements utilized in the system, along with a detailed description of each.
* Security: Developers often overlook this feature when documenting a system. As you browse through existing code, you'll undoubtedly notice security checks applied in various areas, but it is hard to grasp an overall understanding of an application's security model.
Enhance documentation with pictures
It's easy to enhance the four core elements with diagrams and figures. Database systems like SQL Server make it easy to churn out a data model via the Diagrams element within the SQL Server Enterprise Management client. The Diagrams feature assumes the database was properly designed (primary and foreign key relationships) so it can properly identify relationships. If primary and foreign keys are not appropriately defined, relationships are apparent between the elements, thus making it hard for the system to generate a helpful diagram. You should use a tool like Visio or your favorite word processor to create diagrams for your system as you build it.
Screen captures are a great way to document the user interface and provide an overview of a page. You should annotate screen captures to point out various functions. Tools like AnyDoc Software's CAPTUREit simplify the process of grabbing and working with screen captures.
Unified Modeling Language (UML) has evolved into the standard for describing a system with its various diagrams and symbols. UML diagrams include: architecture, sequence, and class.
* An architecture diagram describes the overall system, detailing the various layers of the system and how different users interface with them as well as business rules.
* You can use sequence diagrams to document processes.
* Class diagrams outline system objects.
While IBM Rational provides powerful (and expensive) UML tools, you can create UML diagrams using other products such as Visio.
Insert comments in your code
The most basic form of documentation is code comments. The .NET Framework uses the Java approach to using XML style comments in C#. Then, a developer can use a command-line tool to extract these comments and create basic system documentation of code elements. If the developer properly inserts comments in the code, it's possible to extract object relationships from the comments.
While it's ideal to insert comments as you develop, it can also be useful to insert comments when you make changes to the code, in order to let other developers know what you change and why. These comments are particularly useful for resolving problems that occur after a code change (source control can also address that problem).
Check out these commercial tools
Compiling your own document can be time-consuming. There are various commercial products available to automate the process of documenting your code. Here are two I recommend:
* ASP.NET Documentation Tool: Offers rudimentary code documentation by providing a simple snapshot of all code elements from the source. Similar items like forms, controls, and such are grouped together. (A similar tool is available for SQL Server.)
* PrettyCode.Print for .NET: Provides an easy way to generate hard copies of source code that are readable. The output is formatted with line numbers and so forth.
These tools simply spit out existing code and comments in a readable format. They don't (and cannot) insert any comments on the "how and why" questions developers usually hear when they're examining an application.
Other resources
Microsoft's patterns & practices site has a great book on building secure ASP.NET applications. It includes various security model diagrams that you may use as a starting point for documenting your own system.
You should also check at your favorite bookseller for books focusing on technical documentation and UML. There is plenty of information available for those wanting to know more.
Think of your fellow developer
I feel obligated to create documentation when I think of how much my effort will help another developer do his or her job. Even if you don't have time to create as detailed documentation as you would like, a simple document explaining what the system is supposed to do and why it was built can go a long way in helping to answer questions and resolve problems in the future.
Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.
# posted by MiDBA @ 4/21/2006 10:47:00 AM 
