You Can Use GhostDoc’s Document This with JavaScript
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.
If you haven’t lived in a techie cave the last 10 years, you’ve probably noticed JavaScript’s rise to prominence. Actually, forget prominence. JavaScript has risen to command consideration as today’s lingua franca of modern software development.
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.
Javascript fell into the “scripting” category for me, when I first encountered it, probably around 2001 or 2002. It and something called VBScript competed for the crown of “how to do weird stuff in the browser, half-baked hacky languages.” JavaScript won that battle and cemented itself in my mind as “the thing to do when you want an alert box in the browser.”
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.
Jun
5
By Erik Dietrich
Ghost Doc Says the Damndest Things
Category: .NET Tags: C#, Comments, GhostDoc, SubMain | 5 Comments
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, which can help both with code comment maintenance and the generation of help documentation.
Some years ago, I was doing work for some client or another. Honestly, I have no recollections of specifics with the exception of a preference for exhaustive commenting. Every class, every method, every property, and every field.
Of course, I didn’t learn this at first. I didn’t even learn it in a reasonable time frame. Instead, I learned it close to handover time. And so things got a little desperate.
Enter GhostDoc, My Salvation
Now, depending on your perspective, you might scold me for not diligently commenting all along. I will offer the explanation that the code had no public component and no intended APIs or extensions. It also required no “why” types of explanations; this was simple stuff.
The client cited policy. “We comment everything, and we’re taking over this code, so we want you to do the same.” Okie dokie.
Now, I knew that in a world of code generation and T4 templates, someone must have invented a tool that would generate some sort of comments or another. At the time, a quick Google search brought me to a saving grace: the free tool GhostDoc.
While it did not allow me to carpet bomb my code with comments in a single click (and understandably so), it did allow me to do it for entire files at a time. Good enough. I paid my non-commenting penance by spending an hour or so commenting this way.
And do you know what? It generated pretty respectable comments. I recall feeling impressed because I expected empty template comments. Instead, GhostDoc figured out how to string some verbs and nouns together.
Read More