Sandcastle Help File Builder and FSharp

If you are going to write and release a professional-grade .NET assembly, there are some things that need to be considered: logging, exception handling, and documentation. For .NET components, Sandcastle Help File Builder is the go-to tool to generate documentation as either the old-school .chm file or as a web deploy.

Consider an assembly that contains a Customer record type, an interface for a Customer Repository, and two implementations (In-Memory and ADO.NET)

And you can see what happens. The code base goes from 5 lines of readable code to 21 lines of clutter to make the help file.

One of the tenants of good code is that it is clean –> so we use SOLID principles, run FxCop, and the like. Another tenant of good code is that it is uncluttered –> so we use FSharp, use ROP instead of structured exception handling, and avoid boilerplates and templating. The problem is that we still can’t get away from clutter if we want to have good documentation. Option A is to just drop documentation, a laudable but unrealistic goal, especially in a corporate environment. Option B I am not sure on. I am wondering if I create a separate file in the project just for the code comments. That way the actual code is uncluttered and you can work with it undistracted and the XML still gets generated…