One of my favorite platforms to work on is .Net, either on the Mono implementation or on the Microsoft implementation. We, here at the Macaque, have been recently working on a number of libraries that we want to have for our software to be as good as possible.
One of our goals was to be able to use an addin architecture that we could use to update our applications and give a better service to our users. We don’t want people to have to look at out web page to know if an update has occur and how to install it, that can clearly be done by a machine!!!!
Me, being a open source enthusiast, I decided to use Mono.Addins, which is a framework I have heard about and is used at least one big open source project (Monodevelop). An when I was trying to learn about how to change repositories etc I had to face this. WTF!!!!
There is absolutely no point to release a framework with no documentation. The last thing that someone wants to do is to have to use a piece of code that you don’t really know how to use. Using something without fully understanding it usually gives lots of undesired features (or bugs as other people call them).
There is a nice option in the C# compiler which will treat warning as error and throw XML documentation warning, please use it. I know that documenting is not what we have taking a degree for, but if you are implementing a library you have to use it, there is no other option.
I have taken my own advice and I have started to refactor our DB library with this option set on, yes I have 211 errors which are all documentation related, and you know what, I plan to document every single method to allow people to at least know what is the library doing. Once I have done that, I will have to write our own Addin architecture, why, well because I don’t what to use something I cannot understand, but before I will flush the code reuse idea down the toilet (agggg)
