I’ve long been a fan of agile software development as crystallized in the Agile Manifesto. However, I’ve also felt like the core tenants laid out there are too vague to help software organizations actually be successful. I’ve recently learned of (and signed) the Manifesto for Software Craftsmanship. It is still short on details of how to do it (as I guess any document of this nature must be), but I think it is a nice raising of the bar of the original manifesto:
As aspiring Software Craftsmen we are raising the bar of professional software development by practicing it and helping others learn the craft. Through this work we have come to value:
Not only working software, but also well-crafted software
Not only responding to change, but also steadily adding value
Not only individuals and interactions, but also a community of professionals
Not only customer collaboration, but also productive partnerships
That is, in pursuit of the items on the left we have found the items on the right to be indispensable.
© 2009, the undersigned. this statement may be freely copied in any form, but only in its entirety through this notice.
Bob Martin does a great job expanding on it in this Software Engineering Radio interview.
Software Architecture is largely a matter of communication. One big area of communications is documenting a library, whether for internal or external consumption. It is well-known that written documentation goes out of date the minute you publish it.
The only hope of keeping the documentation up-to-date is to have the it embedded within source code it is illuminating. This allows you to update the doc as you update the code. The Javadoc and C# XML comments are good for this, but don’t give you a good way to provide anything beyond documentation of classes and methods, which often falls short in properly documenting a library or code base.
Doxygen is a capable, open source library that combines the comment-based documentation with a full mark-up language that allows you to add text, diagrams, pages, sections, lists, etc. that allows for robust documentation.
Some of my favorite features include:
- Auto-generated class and collaboration diagrams
- The ability to include hyperlinked source
- Compiled Help format
- PDF format
Here is a nice little C# extension method that allows you to copy all of the properties from one object to another where the names match.
SetPropertiesByName(this object target, object source)
PropertyInfo sourceProperties = source.GetType().GetProperties();
PropertyInfo targetProperties = target.GetType().GetProperties();
foreach (PropertyInfo targetField in targetProperties)
PropertyInfo sourceProperty =
(sourceProperties.Where(f => f.Name == targetField.Name)).FirstOrDefault();
targetField.SetValue(target, sourceProperty.GetValue(source, null), null);
The usage looks this…
I was using AutoMapper for this, but it was overkill for what I needed.
This was way harder to figure out than it should have been, so for the next person that needs to reference an input file in a T4 template by its relative path, here is what you need to do…
1. Include T4Toolbox.tt…
<#@ include file=”T4Toolbox.tt” #>
2. Add hostspecific=”True” to your template setting…
<#@ template language=”C#” hostspecific=”True” #>
3. Import EnvDTE…
<#@ import namespace=”EnvDTE” #>
4. Now TransformationContext.Host.ResolvePath(“SomeFile.sdf”) will return the absolute path of “SomeFile.sdf”.