Editorial Note: I originally wrote this post for the SubMain blog. You can check out the original here, at their site. While you’re there, have a look at GhostDoc for your code documentation and help file generation needs.
I find it sort of surreal to contemplate that, given my own backstory. Years (okay, almost 2 decades) ago, I cut my teeth with C and C++. From there, I branched out to Java, C#, Visual Basic, PHP, and some others I’m probably forgetting. Generally speaking, I came of age during the heyday of object oriented programming.
Oh, sure I had awareness of other paradigms. In college, I had dabbled with (at the time) the esoteric concept of functional programming. And I supplemented “real” programming work with scripts as needed to get stuff done. But object oriented languages gave us the real engine that drove serious work.
Even as it has risen to prominence and inspired a generation of developers, I suppose I’ve never really shed my original baggage with it. While I conceptually understand its role as “assembly language of the web,” I have a hard time not seeing the language that was written in 10 days and named to deliberately confuse people.
GhostDoc, Help, and Intellisense
I’ll come back to that shortly. But first, I’d like to remind you of a prominent GhostDoc feature. Specifically, I’m referring to the “Document This” capability. With your cursor inside of a method or type, you can use this capability to generate instant, well-formated, XML doc comments. Thoroughly documented code sits just a “Ctrl-Sfhift-D” away.
If you work with C# a lot and generate public APIs and/or help documentation, you will love this capability. It doesn’t absolve you of needing to add specific contest. But it does give you a thorough base upon which to build. For example, consider this method from my Chess TDD example codebase.
/// Gets the moves from.
/// <param name="startingLocation">The starting location.</param>
/// <param name="boardSize">Size of the board.</param>
public override IEnumerable<BoardCoordinate> GetMovesFrom(BoardCoordinate startingLocation, int boardSize = Board.DefaultBoardSize)
var oneSquareAwayMoves = GetAllRadialMovesFrom(startingLocation, 1);
return oneSquareAwayMoves.Where(bc => bc.IsCoordinateValidForBoardSize(boardSize));
I took that un-commented method and used GhostDoc to generate this. Now, I Should probably update the summary, but I really don’t see any other deficiencies here. It nails the parameter names and it even escapes the generic return type for readability.
Let’s Take a Look
ShivMethods sounded… interesting, in a prison yard sort of way. As a publicly consumable library, it already has documentation. And, as I learned by playing around, that documentation already gets picked up by IntelliSense. But I figured I’d see what happened by using GhostDoc anyway, for comparison’s sake.
So I lazily put my cursor randomly inside the method and fired away with a Ctrl-Shift-D. Check it out.
As you can see, GhostDoc puts the comment inside of the method and behaves largely as it would with C#. In case you’re wondering about the stylistic difference, GhostDoc does this because it’s the more Microsoft-preferred way. To underscore that, look what happens now when we consume this method with IntelliSense.
As you can see, IntelliSense gives preference to the comments generated by GhostDoc.