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.
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-formatted, XML doc comments. Thoroughly documented code sits just a "Ctrl-Shift-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 ChessTDD 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.
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.
Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.
I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich