Before I get down to the brass tacks of how to do some interesting stuff, I’m going to spin a tale of woe.? Well, I might have phrased that a little strongly.? Call it a tale of corporate drudgery.
In any case, many years ago I worked briefly in a little department, at a little company that seemed to be a corporate drudgery factory.? Oh, the place and people weren’t terrible.? But the work consisted of, well, drudgery.? We ‘consulted’ in the sense that we cranked out software for other companies, for pay.? Our software plumbed the lines of business between client CRMs and ERPs or whatever.? We would write the software, then finish the software, then hand the software over, source code and all.
Naturally, commenting our code and compliance with the coding standard attained crucial importance.? Why?? Well, no practical reason.? It was just that clients would see this code.? So it needed to look professional.? Or something.? It didn’t matter what the comments said.? It didn’t matter if the standard made sense.? Compliance earned you a gold star and a move onto the next project.
As I surveyed the scene surrounding me, I observed a mountain of vacuous comments and dirty, but uniform code.
My Complex Relationship with Code Comments
My brief stay with (and departure from) this organization coincided with my growing awareness of the Software Craftsmanship movement.? Even as they copy and pasted their way toward deadlines and wrote comments announcing that while(x < 6) would proceed while x was less than 6, I became interested in the idea of the self-documenting code.
Up to that point, I had diligently commented each method, file, and type I encountered.? In this regard, I looked out for fellow and future programmers.? But after one too many occasions of watching my own comments turn into lies when someone changed the code without changing the comments, I gave up.? I stopped commenting my code, focusing entirely on extractions, refactoring, and making my code as legible as possible.
I achieved an equilibrium of sorts.? In this fashion, I did less work and stopped seeing my comments become nasty little fibs.? But a single, non-subtle flaw remained in this absolutist approach.? What about documentation of a public (or internal) API?
Naturally, I tried to apply the craftsmanship-oriented reasoning unilaterally.? Just make the public API so discoverable as to render the issue moot.? But that never totally satisfied me because I still liked my handy help screens and IntelliSense info when consuming others’ code.
And so I came to view XML doc comments on public methods as an exception.? These, after all, did not represent “comments.”? They came packaged with your deliverables as your product.? And I remain comfortable with that take today.
Generating Help More Efficiently
Now, my nuanced evolved view doesn’t automatically mean I’ll resume laboriously hand-typing XML comments.? Early in my career, a sort of sad pride in this “work harder, not smarter” approach characterized my development.? But who has time for that anymore?
Instead, with a little bit of investment in learning and tooling, you can do some legitimately cool stuff.? Let me take you through a nifty sequence of steps that you may come to love.
GhostDoc Enterprise
First up, take a look at the GhostDoc Enterprise offering.??? Among other things, this product lets you quickly generate XML comments, customize the default generation template, spell check your code, generate help documentation and more.? Poking through all that alone will probably take some time out of your day.? You should download and play with the product.
Once you are done with that, though, consider how you might get more efficient at beefing up your API.? For the rest of this post, I will use as an example my Chess TDD project.? I use this as a toy codebase for all kinds of demos.
I never commented this codebase, nor did I generate any kind of documentation for it.? Why?? I intended it solely as a teaching tool for test-driven development, and never packaged it for others’ consumption.? Let’s change that today.
Adding Comments
Armed with GhostDoc enterprise, I will first generate some comments.? The Board class makes a likely candidate since that offers theoretical users the most value.
First up, I need to add XML doc comments to the file.? I can do this by right clicking in the file, and selecting “Document Type” from the GhostDoc Enterprise context menu.? Here’s what the result looks like.
The default template offers a pretty smart guess at intent, based on good variable naming.? For my fellow clean code enthusiasts out there, you can even check how self-documenting your code is by the quality of the comments GhostDoc creates.? But still, you probably want to take a human pass through, checking and tweaking where needed.
Building Help Documentation
All right.? With comments in place for the public facing API of my little project, we can move on to the actual documentation.? Again, easy enough.? Select “Tools -> GhostDoc Enterprise -> Build Help Documentation” from the main menu.? You’ll see this screen.
Notice that you have a great deal of control over the particulars.? Going into detail here is beyond the scope of my post, but you can certainly play around.? I’ll take the defaults and build a CHM help file.? Once I click “OK”, here’s what I see (once I go to the board class).
Pretty slick, huh?? Seriously.? With just a few clicks, you get intelligently commented public methods and a professional-looking help file.? (You can also have this as web-style documentation if you want).? Obviously, I’d want to do some housekeeping here if I were selling this, but it does a pretty good job even with zero intervention from me.
Do It From the Build
Only one bit of automation remains at this point.? And that’s the generation of this documentation from the build.? Fortunately, GhostDoc Enterprise makes that simple as well.
Any build system worth its salt will, of course, let you hook command line invocations into your build.? GhostDoc Enterprise offers one up for just this occasion.? You can read a succinct guide on that right here.? With a single command, you can point it at your solution, a help configuration, and a project configuration, and generate the help file.? Putting it where you want is then easy enough.
Tying this in with an automated build or CI setup really ties everything together, including the theme of this post.? Automating the generation of clean, helpful documentation of your clean code, building it, and packaging it up all without human intervention pretty much represents the pinnacle of delivering a professional product.
4 Comments. Leave new
Since you generated your documentation as a CHM help file; have you then overcome the issues Windows presents with moving them around?
i.e. it screams about security if you attempt to view from a network location and/or if you try to open from a download.
Joseph, we are generating CHM using the Microsoft HTML Help compiler – https://support.submain.com/kb/a49/installing-microsoft-html-help-workshop.aspx – which generates a standard CHM file. The security feature you mention is not the CHM format itself but how Windows treats CHM downloaded from a public or private share – Windows marks these for security purposes. Here is how these can be unblocked – SubMain KB – Unblocking downloaded CHM documentation files
any way to run a command line to generate code documentation as html?
Robert, yes, it is very easy in fact. You can follow the example in this article and create your own help configuration for HTML docs – select “Website” in the Documentation Formats and save the help configuration with your own unique name. Then you run the command line tool with your help configuration name. You can learn more in the post below, and see Example 2 for the HTML/Website format steps – https://support.submain.com/kb/a45/ghostdoc-enterprise-command-line-parameters.aspx