Tuesday, September 16, 2014

Document your code, what's next?

Today I have been working on my release version of my project. 

Releasing a project means to me that
  • the features are developed
  • the features are tested
  • the database was adapted
  • the code is re-factored
  • the code is styled
    ... and last and worst
  • the missing comments (I left to the end as always) are added.

To check style and comments I use the tool "StyleCop" which is quite cool but also a pain in the ... hmmm,... neck. This means that at least all summary tags are filled out. After some routine you don't even think of the benefit of doing this. So what is the benefit of the summary tags (and of course there are a lot more tags to mention like the value, returns, param,...)?

In the msdn description of the summary tag ( http://msdn.microsoft.com/en-us/library/2d6dt3kf.aspx ) first of all the object browser window is mentioned, but I don't think that this is THE benefit for most developers. In fact I use the object browser window as good as never... or let's say never.

The article also mentions documentation tools like sandcastle (what is a bad example, because the project is no longer under active development by microsoft ... see http://sandcastle.codeplex.com/ ... even if there is a new open source branch of the project http://shfb.codeplex.com/ ). This project is much too complicated for me. I would like to generate a damn easy chm-file or something which looks great and what makes no troubles at all. 

There are commercial product which seemed to accept my challenge of "creating an easy to use tool" like 
  • vsdocman ( http://www.helixoft.com/vsdocman/overview.html ) or 
  • document X! ( https://www.innovasys.com/product/dx/features_vsnet.html ) or 
  • live documenter ( http://livedocumenter.com/ ) 
did. Other open source project seemed to make a complicated task ( generating a documentation ) more or less impossible (like doxygen). An other approach is to simply provide an xslt file to the generated xml-documentation (out of visual studio).

Finally I decided to use the github project docu ( http://docu.jagregory.com/ ). I downloaded the source, compiled it and it simply worked. I don't really like the template, but this is customizable, so hurray ... I found a solution which generates static and simple web pages. These pages can be opened from inside the visual studio (even if this solution is not yet perfect) using ctrl w + w.

cheers,
Daniel

No comments: