Using attributes to document alterations

• Download source files - 40.4 Kb

Introduction

In most of the projects in which I worked, the most common scenario during the maintenance of a software are the following:

1. A certain module is liberated for production (v 1.0).
2. With passing of time, alterations are accomplished in this module.
3. In most of the "commercial" applications it is common that alterations in certain modules also alter the model of data. In this point, script files for updations in the base are created (usually for a DBA).
4. The final user needs to have access to what was altered (formally), in the same measure that the development team involved in the project needs to be updated about all the alterations. In this point, two new workmanships are created (usually more refined documents).

The experience that I have been having can be summarized in the following list of disadvantages:

• The creation of documents and / or files out of the "development atmosphere"; it is not natural and it demands people are dedicated to this work. (or it takes a lot of the precious time of the programmers)
• The development team works faster than the dedicated people the documentation. This turns the documentation obsolete in little time.
• Only the scripts for updating of the database are maintained with certain discipline.

The idea here is to show the development of a part (application that generates documentation) of the alternative solution that I am creating to outline the subjects exposed above. The illustration below displays which are the parts of the solution that are to be completed.

The attribute "to mark" the alterations

The attribute UpdateDocumentationAttribute is an example and shows how it can be made to document the alterations. I placed some information that will be used by the application for version updating. The code that uses the attribute would be as in the fragment below:

#region Version 1.0.0.1
[assembly: UpdateDocumentationAttribute("1.0.0.1",
    "SampleAssembly1 - Sumary for developers", 
    "SampleAssembly1 - Sumary for final users", 
    UpdatePriority.Medium, "20/05/2003")]
#endregion

See that there are two description types. A technique and another that should be used to describe to the final users the alterations. A program that generates documentation can take advantage of this information to generate different documents, according to the context. In the current version, the documentation software generates all the information as only document type.

The application that generates documentation

There is not anything very special in the programming of this application. What is done here is the following:

• To allow to the user to select a period of dates to visualize alterations.
• To allow to the user to select assemblies for which he wants to visualize the alterations.
• To generate a file XML with base containing the information loaded from the assemblies.
• To transform the file XML into a document HTML.

Observation: The generation of XML was made to facilitate the inclusion of new information. It's "extensive" (due to two additional classes), but the code is readable.

Todo list

• To increase the filter options (for priority, author, key word etc.)
• To improve the programming of the filter.
• To allow the user to select options for resulting HTML. (XSL used here is very basic, necessary to research a little more. If you have some format suggestion doesn't forget to send me a copy. : -)
• To use pagination for very extensive results.
• To transform this application as an add-in for VS.NET. In this case, the selection of the assemblies will be removed and the information will be collected now from the solution that's open.

Conclusion

I want to say that I don't know if in the course of time, with a lot of alterations, the "loader" of the assembly will be prejudiced. I would like to thank to Ricardo Origuchi for his research work in the transforms using XSL. It was worth a lot! My English leaves a lot to be wanted, but I am working to improve this... ;-)