Click here to Skip to main content
Click here to Skip to main content

Using attributes to document alterations

, 27 May 2003
Rate this:
Please Sign up or sign in to vote.
Using attributes to solve subjects linked to the daily work of software maintenance.

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.

Structure completes

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.

doc generator screenshot

sample document

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... Wink | ;-)

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Palladino
Web Developer
Brazil Brazil
To develop software is the best work of the world!

Comments and Discussions

 
GeneralApplication Frameworks Pinmemberapferreira3-Jun-03 2:35 
GeneralRe: Application Frameworks PinmemberPalladino3-Jun-03 6:18 
GeneralBetter code than article PinsussAnonymous28-May-03 7:10 
Suspicious | :suss: 3!

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web01 | 2.8.141022.2 | Last Updated 28 May 2003
Article Copyright 2003 by Palladino
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid