On Documentation for (and by) Developers

The government's view of the economy could be summed up in a few short phrases: If it moves, tax it. If it keeps moving, regulate it. And if it stops moving, subsidize it.  - Ronald Reagan

This has become a personal pet - peeve of mine, having been in various developer groups using the .NET platform since 2001 (ancient history, to be sure -- at least by Internet standards).

When I write a class library, if there is even the HINT that it may be used by other developers (or  -- even by me myself at some later date) I've learned to produce decent documentation in the standard XML comment format that has been available in .NET since the very first BETA 1.0 was distributed at the Orlando PDC (Professional Developers Conference) in 2000. 

Here's the "thing": as you progress in your career as a professional .NET developer, you'll learn to produce libraries and classes of useful code that you'll use again and again. The idea is that as you gain more and more experience, the personal resources you have developed to solve common programming tasks will increase, and your job as a programmer should get progressively easier - provided that you have documented your code!  Code I look at that's over six months old - unless it is documented well -- presents a challenge as I try to remember what it does and how it does it. Maybe I'm just having a Senior Moment - but I suspect that this  problem exists for everyone.

The standard XML  format of documentation works well  because there are well established tools (NDoc, Sandcastle, etc.) that can use this metadata to produce professional - quality CHM or HSX Visual Studio / MSDN type help files.

But even more importantly, if you as a developer enable the "XML documentation" path in the Build tab of your project's configuration property sheet, Visual Studio will generate it's standard XML documentation file that normally sits right next to the built assembly in the build output path.

And guess what? When you or anybody else loads this project, that XML documentation file is used  by Visual Studio to provide the developer with - Intellisense! The Intellisense that you - the original developer - authored. You can use, for example, the <remarks>... element to give developers instructional comments that will shorten their learning curve in using your code -- which they probably have never worked with before, no? Looky here:

xmldocu

Putting comments inline inside the body of your methods, or after the end of a line of code, or even inline inside a parameter list with /* comment here */ is useful of course. But standard XML documentation has a specific schema and must be placed just above the class or method declaration in order to be used by the IDE in the manner I've described.

There are several tools that can be used to make this task easier; the best of which (I think) is GhostDoc produced by Roland Weigelt.

In fact I distinctly remember Roland emailing me some time ago asking if it was OK to use some code that I had published for his GhostDoc add-in project -- and of course the answer was that I was delighted.  GhostDoc is indispensible if you strive to be a professional developer and document your code. It automatically produces "best - guess" documentation that you can embellish or improve very easily - and all you need to do is highlight the first (signature)  line of your method, right - click, and choose "Document this". Jeesh -- it doesn't get any easier than this!

Producing quality, standards - based documentation for your work not only establishes you as a professional who cares about others, it can also save a lot of man-hours of work for any developer who is expected to use your creation in their work. Developers often say or think, "I don't have the time to produce documentation". Actually, it's the other way around - if you don't make the time to  produce documentation, you may not have time left for development.

Remember - we don't develop code in a vacuum, even if we are "a team of one". Some months from now, YOU may be the person who is happy that the documentation was provided (by you).

Roland, thanks for providing a great tool!

Comments

Post a Comment

Popular posts from this blog

FIREFOX / IE Word-Wrap, Word-Break, TABLES FIX

One of the most annoying things a developer (who would normally delight in writing code, not futzing with markup) can have is getting rendering issues between different browsers. The two biggest players are of course Internet Exploder and Firefart (as I lovingly like to refer to each). In most cases that's going to take care of 98 percent of your total site traffic. IE has had a proprietary "word-break" style attribute for a long time, and this made it into the CSS 3.0 spec. But that doesn't necessarily help you with Firefox right now. Firefox literally - (and I consider this completely idiotic, since it's been in their bug database for FIVE YEARS) does not have a reliable CSS style element to force table cell content to break in the middle of a word in order to stop the content from expanding your table / div off the page or over other content on the page. Here's a partial fix, which will work for most tables and browsers. The style declaration (I call it m
Read more

Some observations on Script Callbacks, "AJAX", "ATLAS" "AHAB" and where it's all going.

I've taken a more than cursory interest in the whole Remote Scripting (.NET species) vs. AJAX and now ATLAS discussion, mostly because I started using Remote Scripting since Microsoft first released it, and because I continued to refine it after seeing Brent Ashley's excellent work with JSRS, which was one of the first "real" cross-browser solutions back in 2000 (that's the turn of the Century for you history buffs). Now Bertrand Leroy, a Microsoft guy whose work I like , has authored some very interesting ASP.NET 2.0 script callback stuff that he points to on his blog, and he is obviously (at least, to me he is) involved quite heavily in the development of this new ATLAS infrastructure that they'll preview at PDC. Leroy's most recent post brings to the surface what I agree are the major differences between the "AJAX a - la .NET" approach as popularized by Michael Swartz with his AJAX.NET library, and Leroy's RefreshPanel, the ASP.NET 2.0 b
Read more

IE7 - Vista: "Internet Explorer has stopped Working"

Image
This one was a bitch. All of a sudden for no reason at all, out of the blue, I get this dialog "internet Explorer has stopped working". I didn't install any new software, crap- I didn't do anything! So here I am using FIREFART to go on the internet and find out what to do! Damn! Good thing I've got the sucker on the same machine (I'm not "anti-Firefox", i just don't use it that much except to check my page renderings). The Fix The fix (at least for me): 1) Go into Control Panel, and choose "Internet Options". 2) Under the "Advanced" tab, press the "RESET" button at the lower right: Don't ask me why this happens, or why the fix works. That's a BUG, D00D - I don't care how you slice it!
Read more