Geeks With Blogs

News Google

Nick Harrison Blog<Nick>.Next()

I have spoken in the past about the burden that keeping documentation up to date. This can be quiet a cumbersome burden.

At the same time, we clearly need some documentation and are often required to provide more documentation than is absolutely needed.

With all this in mind, I have been thinking about ways to design code to lessen the amount of documentation that has to be written and maintained.


Turns out, there are many cases where such design changes improves the quality of code, lowers the maintenance costs, and allows us to potentially generate more documentation.

On several projects that I am working on, we end up following a DTO pattern for transferring data from the app side to the presentation side. One of the annoyances is keeping track of the relationship between Entity, DTO, and Repository. The names will vary across implementations, but you will often have a one to one relationship between an Entity and a Data Transfer Object. Both of these may be served from a Repository responsible for interacting with the database.

I have started relying on Generic parameter to explicitly state this relationship in code. We can then use reflection to pull out these relationships and help build out the documentation.

Consider the following class declaration for an Entity:


public abstract class EntityBase<TDto, TRepository, TEntity>: IEntity<TDto>

where TRepository : RepositoryBase<TEntity >, new()

where TDto : DtoRootBase

where TEntity : class, IRotEntity



The IEntity interface needs to know the DTO to require strongly typed methods for GetDto, etc. The Repository needs to know the Entity to be able to provide strongly typed signatures for methods such as Get and Save. By specifying the Repository, we now have all the details needed to implement a Save method in the base class as well as wire up constructors that will retrieve object details from the database.


The method signature for declaring classes is complicated somewhat but not overly. Consider the following class declaration:



public class MemberEntity : BaseEntity<MemberDto , MemberRepository , MemberEntity > , IRootEntity



Granted it looks a little odd specifying the class as a generic parameter to the base class, but it is not a difficult pattern to follow.


But we know have enough details to drive producing a report linking these pivotal objects together. This framework will verify that these details are accurate and update.


We also get some value added in the implementation in that key methods that would not normally be strongly typed are strongly typed and the usage of the Entity is more streamlined by allowing us to get a fully initialized entity through the constructor.



MemberEntity member = new MemberEntity(12);



Posted on Friday, July 9, 2010 5:02 PM | Back to top

Comments on this post: Revisiting Agile Documentation

comments powered by Disqus

Copyright © Nick Harrison | Powered by: