Today, I'd like to tackle a subject that inspires ambivalence in me. Specifically,
I mean the subject of automated text generation (including a common, specific flavor:
code generation).

If you haven't encountered this before, consider a common example. When you
file->new->(console) project, Visual Studio generates a Program.cs file.
This file contains standard includes, a program class, and a public static void method
called "Main." Conceptually, you just triggered text (and code) generation.

Many schemes exist for doing this. Really, you just need a templating scheme
and some kind of processing engine to make it happen. Think of ASP MVC, for
instance. You write markup sprinkled with interpreted variables (i.e. Razor),
and your controller object processes that and spits out pure HTML to return as the
response. PHP and other server side scripting constructs operate this way and
so do code/text generators.

However, I'd like to narrow the focus to a specific case: T4
templates. You can use this powerful construct to generate all manner of
text. But use discretion, because you can also use this powerful construct to
make a huge mess. I wrote a
post about the potential perils some years back, but suffice it to say that you
should take care not to automate and speed up copy and paste programming. Make
sure your case for use makes sense.

The Very Basics

With the obligatory disclaimer out of the way, let's get down to brass tacks.
I'll offer a lightning fast getting started primer.

Open some kind of playpen project in Visual Studio, and add a new item. You
can find the item in question under the "General" heading as "Text Template."

Give it a name. For instance, I called mine "sample" while writing this post.
Once you do that, you will see it show up in the root directory of your project as
Sample.tt. Here is the text that it contains.

Save this file. When you do so, Visual Studio will prompt you with a message
about potentially harming your computer, so something must be happening behind the
scenes, right? Indeed, something has happened. You have generated the
output of the T4 generation process. And you can see it by expanding the caret
next to your Sample.tt file as shown here.

If you open the Sample.txt file, however, you will find it empty. That's because
we haven't done anything interesting yet. Add a new line with the text "hello
world" to the bottom of the Sample.tt file and then save. (And feel free to
get rid of that message about harming your computer by opting out, if you want).
You will now see a new Sample.txt file containing the words "hello world."

Beyond the Trivial

While you might find it satisfying to get going, what we've done so far could be accomplished
with file copy. Let's take advantage of T4 templating in earnest. First
up, observe what happens when you change the output extension. Make it something
like .blah and observe that saving results in Sample.blah. As you can see, there's
more going on than simple text duplication. But let's do something more interesting.

Update your Sample.tt file to contain the following text and then click save.

Hello World 0
Hello World 1
Hello World 2
Hello World 3
Hello World 4
Hello World 5
Hello World 6
Hello World 7
Hello World 8
Hello World 9

Pretty neat, huh? You've used the <# #> tokens to surround first class
C# that you can use to generate text. I imagine you can see the potential here.

Oh, and what happens when you type malformed C#? Remove the semicolon and see
for yourself. Yes, Visual Studio offers you feedback about bad T4 template files.

Use Cases

I'll stop here with the T4 tutorial. After all, I aimed only to provide an introduction.
And I think that part of any true introduction involves explaining where and how the
subject might prove useful to readers. So where do people reasonably use these
things?

Perhaps the most common usage scenario pertains to ORMs and the so-called impedance
mismatch problem. People create code generation schemes that examine databases
and spit out source code that matches with them. This approach spares the significant
performance hit of some kind of runtime scheme for figuring this out, but without
forcing tedious typing on dev teams. Entity Framework makes use of T4 templates.

I have seen other uses as well, however. Perhaps your organization puts involved
XML configuration files into any new projects and you want to generate these without
copy and paste. Or, perhaps you need to replace an expensive reflection/runtime
scheme for performance reasons. Maybe you have a good bit of layering boilerplate
and object mapping to do. Really, the sky is the limit here, but always bear
in mind the caveat that I offered at the beginning of this post. Take care not
to let code/text generation be a crutch for cranking out anti-patterns more rapidly.

The GhostDoc Use Case

I will close by offering a tie-in with the GhostDoc offering
as the final use case. If you use GhostDoc to generate comments for methods
and types in your codebase, you should know that you can customize the default generations
using T4 templates. (As an aside, I consider this a perfect use case for templating
-- a software vendor offering a product to developers that assists them with writing
code.)

If you open GhostDoc's options pane and navigate to "Rules" you will see the following
screen. Double clicking any of the templates will give you the option to edit
them, customizing as you see fit.

You can thus do simple things, like adding some copyright boilerplate, for instance.
Or you could really dive into the weeds of the commenting engine to customize to your
heart's content (be careful here, though). You can exert a great deal of control.

T4 templates offer you power and can make your life easier when used judiciously.
They're definitely a tool worth having in your tool belt. And, if you make use
of GhostDoc, this is doubly true.

If you spend enough years writing software, sooner or later, your chosen vocation
will force you into reverse engineering. Some weird API method with an inscrutable
name will stymie you. And you'll have to plug in random inputs and examine the
outputs to figure out what it does.

Clearly,
this wastes your time. Even if you enjoy the detective work, you can't argue
that an employer or client would view this as efficient. Library and API code
should not require you to launch a mystery investigation to determine what it does.

Instead, such code should come with appropriate documentation. This documentation
should move your focus from wondering what the code does to contemplating how best
to leverage it. It should make your life easier.

But what constitutes appropriate documentation? What particular characteristics
does it have? In this post, I'd like to lay out some elements of helpful code
documentation.

Elements of Style

Before moving on to what the documentation should contain, I will speak first about
its stylistic properties. After all, poorly written documentation can tank understanding,
even if it theoretically contains everything it should. If you're going to write
it, make it good.

Now don't get me wrong -- I'm not suggesting you should invest enough time to make
it a literary masterpiece. Instead, focus on three primary characteristics of
good writing: clarity, correctness, and precision. You want to make sure that
readers understand exactly what you're talking about. And, obviously, you cannot
get anything wrong.

The importance of this goes beyond just the particular method in question. It
affects your entire credibility with your userbase. If you confuse them with
ambiguity or, worse, get something wrong, they will start to mistrust you. The
documentation becomes useless to them and your reputation suffers.

Examples

Once you've gotten your house in order with stylistic concerns in the documentation,
you can decide on what to include. First up, I cannot overstate the importance
of including examples.

Whether you find yourself documenting a class, a method, a web service call, or anything
else, provide examples. Show the users the code in action and let them
apply their pattern matching and deduction skills. In case you hadn't noticed,
programmers tend to have these in spades.

Empathize with the users of your code. When you find yourself reading manuals
and documentation, don't you look for examples? Don't you prefer to grab them
and tweak them to suit your current situation? So do the readers of your documentation.
Oblige them. (See <example
/>)

Conditions

Let me define these in broad terms so that you understand what I mean. Respectively,
preconditions, postconditions, and invariants are things that must be true before
your code executes, things that must be true after it executes, and things that must
remain true throughout.

Documenting this information for your users saves them trial and error misery.
If you leave this out, they may have to discover for themselves that the method won't
accept a null parameter or that it never returns a positive number. Spare them
that trial and error experimentation and make this clear. By telling them explicitly,
you help them determine up front whether this code suits their purpose or not. (See <remarks
/> and <note
/>)

Related Elements

Moving out from core principles a bit, let's talk about some important meta-information.
People don't always peruse your documentation in "lookup" mode, wanting help about
a code element whose name they already know. Instead, sometimes they will 'surf'
the documentation, brainstorming the best way to tackle a problem.

For instance, imagine that you want to design some behavior around a collection type.
Familiar with List, you look that up, but then maybe you poke around to see what inherits
from the same base or implements the same interface. By doing this, you hope
to find the perfect collection type to suit your needs.

Make this sort of thing easy on readers of your documentation by offering a concept
of "related" elements. Listing OOP classes in the same hierarchy represents
just one example of what you might do. You can also list all elements with a
similar behavior or a similar name. You will have to determine for yourself
what related elements make sense based on context. Just make sure to include
them, though. (See <seealso
/> )

Pitfalls and Gotchas

Last, I'll mention an oft-overlooked property of documentation. Most commonly,
you might see this when looking at the documentation for some API call. Often,
it takes the form of "exceptions thrown" or "possible error codes."

But I'd like to generalize further here to "pitfalls and gotchas." Listing out
error codes and exceptions is great because it lets users know what to expect when
things go off the rails. But these aren't the only ways that things can go wrong,
nor are they the only things of which users should be aware.

Take care to list anything out here that might violate the principle
of least surprise or that could trip people up. This might include things
like, "common ways users misuse this method" or "if you get output X, check that you
set Y correctly." You can usually populate this section pretty easily whenever
a user struggles with the documentation as-is.

Wherever you get the pitfalls, just be sure to include them. Believe it or not,
this kind of detail can make the difference between adequate and outstanding documentation.
Few things impress users as much as you anticipating their questions and needs. (See <exception
/>, <returns
/> and <remarks
/>)

Documentation Won't Fix Bad Code

In closing, I would like to offer a thought that returns to the code itself.
Writing good documentation is critically important for anyone whose code will be consumed
by others -- especially those selling their code. But it all goes for naught
should you write bad or buggy code, or should your API present a mess to your users.

Thus I encourage you to apply the same scrutiny to the usability of your API that
I have just encouraged you to do for your documentation. Look to ensure that
you offer crisp, clear abstractions. Name code elements appropriately.
Avoid surprises to your users.

Over the last decade or so, organizations like Apple have moved us away from hefty
user manuals in favor of "discoverable" interfaces. Apply the same principle
to your code. I tell you this not to excuse you from documentation, but to help
you make your documentation count. When your clean API serves as part of your
documentation, you will write less of it, and what you do write will have higher value
to readers.

About the Author

Erik Dietrich

Elements of Helpful Code Documentationhttp://submain.com/blog/PermaLink,guid,27431d96-ad2e-459a-9f38-b1f0c3b89427.aspxhttp://submain.com/blog/ElementsOfHelpfulCodeDocumentation.aspx
Tue, 25 Oct 2016 18:53:00 GMT<p>
If you spend enough years writing software, sooner or later, your chosen vocation
will force you into reverse engineering.&nbsp; Some weird API method with an inscrutable
name will stymie you.&nbsp; And you'll have to plug in random inputs and examine the
outputs to figure out what it does.
</p>
<p>
<img title="blog-elements-of-helpful-code-documentation" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; float: right; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="blog-elements-of-helpful-code-documentation" src="http://submain.com/blog/content/binary/Open-Live-Writer/d2b01e691374_CA8C/blog-elements-of-helpful-code-documentation_3.png" width="160" align="right" height="210">Clearly,
this wastes your time.&nbsp; Even if you enjoy the detective work, you can't argue
that an employer or client would view this as efficient.&nbsp; Library and API code
should not require you to launch a mystery investigation to determine what it does.
</p>
<p>
Instead, such code should come with appropriate documentation.&nbsp; This documentation
should move your focus from wondering what the code does to contemplating how best
to leverage it.&nbsp; It should make your life easier.
</p>
<p>
But what constitutes appropriate documentation?&nbsp; What particular characteristics
does it have?&nbsp; In this post, I'd like to lay out some elements of helpful code
documentation.
</p>
<h4>Elements of Style
</h4>
<p>
Before moving on to what the documentation should contain, I will speak first about
its stylistic properties.&nbsp; After all, poorly written documentation can tank understanding,
even if it theoretically contains everything it should.&nbsp; If you're going to write
it, make it good.
</p>
<p>
Now don't get me wrong -- I'm not suggesting you should invest enough time to make
it a literary masterpiece.&nbsp; Instead, focus on three primary characteristics of
good writing: clarity, correctness, and precision.&nbsp; You want to make sure that
readers understand exactly what you're talking about.&nbsp; And, obviously, you cannot
get anything wrong.
</p>
<p>
The importance of this goes beyond just the particular method in question.&nbsp; It
affects your entire credibility with your userbase.&nbsp; If you confuse them with
ambiguity or, worse, get something wrong, they will start to mistrust you.&nbsp; The
documentation becomes useless to them and your reputation suffers.
</p>
<h4>Examples
</h4>
<p>
Once you've gotten your house in order with stylistic concerns in the documentation,
you can decide on what to include.&nbsp; First up, I cannot overstate the importance
of including examples.
</p>
<p>
Whether you find yourself documenting a class, a method, a web service call, or anything
else, <em>provide examples</em>.&nbsp; Show the users the code in action and let them
apply their pattern matching and deduction skills.&nbsp; In case you hadn't noticed,
programmers tend to have these in spades.
</p>
<p>
Empathize with the users of your code.&nbsp; When you find yourself reading manuals
and documentation, don't you look for examples?&nbsp; Don't you prefer to grab them
and tweak them to suit your current situation?&nbsp; So do the readers of your documentation.&nbsp;
Oblige them. (See <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#example" target="_blank">&lt;example
/&gt;</a>)
</p>
<h4>Conditions
</h4>
<p>
Next up, I'll talk about the general consideration of "conditions."&nbsp; By this,
I mean three basic types of conditions: <a href="https://www.cs.umd.edu/class/fall2002/cmsc214/Projects/P1/proj1.contract.html" target="_blank">preconditions,
postconditions, and invariants</a>.
</p>
<p>
Let me define these in broad terms so that you understand what I mean.&nbsp; Respectively,
preconditions, postconditions, and invariants are things that must be true before
your code executes, things that must be true after it executes, and things that must
remain true throughout.
</p>
<p>
Documenting this information for your users saves them trial and error misery.&nbsp;
If you leave this out, they may have to discover for themselves that the method won't
accept a null parameter or that it never returns a positive number.&nbsp; Spare them
that trial and error experimentation and make this clear.&nbsp; By telling them explicitly,
you help them determine up front whether this code suits their purpose or not. (See <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#remarks" target="_blank">&lt;remarks
/&gt;</a> and <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#note" target="_blank">&lt;note
/&gt;</a>)
</p>
<h4>Related Elements
</h4>
<p>
Moving out from core principles a bit, let's talk about some important meta-information.&nbsp;
People don't always peruse your documentation in "lookup" mode, wanting help about
a code element whose name they already know.&nbsp; Instead, sometimes they will 'surf'
the documentation, brainstorming the best way to tackle a problem.
</p>
<p>
For instance, imagine that you want to design some behavior around a collection type.&nbsp;
Familiar with List, you look that up, but then maybe you poke around to see what inherits
from the same base or implements the same interface.&nbsp; By doing this, you hope
to find the perfect collection type to suit your needs.
</p>
<p>
Make this sort of thing easy on readers of your documentation by offering a concept
of "related" elements.&nbsp; Listing OOP classes in the same hierarchy represents
just one example of what you might do.&nbsp; You can also list all elements with a
similar behavior or a similar name.&nbsp; You will have to determine for yourself
what related elements make sense based on context.&nbsp; Just make sure to include
them, though. (See <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#seealso" target="_blank">&lt;seealso
/&gt;</a> )
</p>
<h4>Pitfalls and Gotchas
</h4>
<p>
Last, I'll mention an oft-overlooked property of documentation.&nbsp; Most commonly,
you might see this when looking at the documentation for some API call.&nbsp; Often,
it takes the form of "exceptions thrown" or "possible error codes."
</p>
<p>
But I'd like to generalize further here to "pitfalls and gotchas."&nbsp; Listing out
error codes and exceptions is great because it lets users know what to expect when
things go off the rails.&nbsp; But these aren't the only ways that things can go wrong,
nor are they the only things of which users should be aware.
</p>
<p>
Take care to list anything out here that might violate the <a href="https://en.wikipedia.org/wiki/Principle_of_least_astonishment" target="_blank">principle
of least surprise</a> or that could trip people up.&nbsp; This might include things
like, "common ways users misuse this method" or "if you get output X, check that you
set Y correctly."&nbsp; You can usually populate this section pretty easily whenever
a user struggles with the documentation as-is.
</p>
<p>
Wherever you get the pitfalls, just be sure to include them.&nbsp; Believe it or not,
this kind of detail can make the difference between adequate and outstanding documentation.&nbsp;
Few things impress users as much as you anticipating their questions and needs. (See <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#exception" target="_blank">&lt;exception
/&gt;</a>, <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#returns" target="_blank">&lt;returns
/&gt;</a> and <a href="http://support.submain.com/kb/a46/xml-comment-tags-supported-by-ghostdoc.aspx#remarks" target="_blank">&lt;remarks
/&gt;</a>)
</p>
<h4>Documentation Won't Fix Bad Code
</h4>
<p>
In closing, I would like to offer a thought that returns to the code itself.&nbsp;
Writing good documentation is critically important for anyone whose code will be consumed
by others -- especially those selling their code.&nbsp; But it all goes for naught
should you write bad or buggy code, or should your API present a mess to your users.
</p>
<p>
Thus I encourage you to apply the same scrutiny to the usability of your API that
I have just encouraged you to do for your documentation.&nbsp; Look to ensure that
you offer crisp, clear abstractions.&nbsp; Name code elements appropriately.&nbsp;
Avoid surprises to your users.
</p>
<p>
Over the last decade or so, organizations like Apple have moved us away from hefty
user manuals in favor of "discoverable" interfaces.&nbsp; Apply the same principle
to your code.&nbsp; I tell you this not to excuse you from documentation, but to help
you make your documentation count.&nbsp; When your clean API serves as part of your
documentation, you will write less of it, and what you do write will have higher value
to readers.
</p>
<p>
<a style="font-size: 1.2em; line-height: 1.5" href="http://submain.com/ghostdoc/video/?skipto=intro" target="_blank">Learn
more about how GhostDoc can help simplify your XML Comments, produce and maintain
quality help documentation.</a>
</p>
<h4>About the Author
</h4>
<h5>Erik Dietrich
</h5>
<p>
I'm a passionate software developer and active blogger. Read about me at <a href="http://www.daedtech.com/additional-information/about" target="_blank">my
site</a>. <a href="http://submain.com/blog/CategoryView,category,ErikDietrich.aspx" target="_blank">View
all posts by Erik Dietrich</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=27431d96-ad2e-459a-9f38-b1f0c3b89427" />http://submain.com/blog/CommentView,guid,27431d96-ad2e-459a-9f38-b1f0c3b89427.aspxArticlesDocumentationErikDietrichGhostDochttp://submain.com/blog/Trackback.aspx?guid=44e0ff6c-06ae-479f-9d48-c369ffbb0e2dhttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,44e0ff6c-06ae-479f-9d48-c369ffbb0e2d.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,44e0ff6c-06ae-479f-9d48-c369ffbb0e2d.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=44e0ff6c-06ae-479f-9d48-c369ffbb0e2d

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.

About the Author

Erik Dietrich

Generate Documentation from Your Buildhttp://submain.com/blog/PermaLink,guid,44e0ff6c-06ae-479f-9d48-c369ffbb0e2d.aspxhttp://submain.com/blog/GenerateDocumentationFromYourBuild.aspx
Thu, 06 Oct 2016 14:54:00 GMT<p>
Before I get down to the brass tacks of how to do some interesting stuff, I'm going
to spin a tale of woe.&nbsp; Well, I might have phrased that a little strongly.&nbsp;
Call it a tale of corporate drudgery.
</p>
<p>
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.&nbsp; Oh, the place and people weren't
terrible.&nbsp; But the work consisted of, well, drudgery.&nbsp; We 'consulted' in
the sense that we cranked out software for other companies, for pay.&nbsp; Our software
plumbed the lines of business between client CRMs and ERPs or whatever.&nbsp; We would
write the software, then finish the software, then hand the software over, source
code and all.
</p>
<p>
Naturally, commenting our code and compliance with the coding standard attained crucial
importance.&nbsp; Why?&nbsp; Well, no practical reason.&nbsp; It was just that clients
would see this code.&nbsp; So it needed to look professional.&nbsp; Or something.&nbsp;
It didn't matter what the comments said.&nbsp; It didn't matter if the standard made
sense.&nbsp; Compliance earned you a gold star and a move onto the next project.
</p>
<p>
As I surveyed the scene surrounding me, I observed a mountain of vacuous comments
and dirty, but uniform code.
</p>
<h4>My Complex Relationship with Code Comments
</h4>
<p>
My brief stay with (and departure from) this organization coincided with my growing
awareness of the Software Craftsmanship movement.&nbsp; Even as they copy and pasted
their way toward deadlines and wrote comments announcing that while(x &lt; 6) would
proceed while x was less than 6, I became interested in the idea of the self-documenting
code.
</p>
<p>
Up to that point, I had diligently commented each method, file, and type I encountered.&nbsp;
In this regard, I looked out for fellow and future programmers.&nbsp; 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.&nbsp; I stopped commenting my code,
focusing entirely on extractions, refactoring, and making my code as legible as possible.
</p>
<p>
I achieved an equilibrium of sorts.&nbsp; In this fashion, I did less work and stopped
seeing my comments become nasty little fibs.&nbsp; But a single, non-subtle flaw remained
in this absolutist approach.&nbsp; What about documentation of a public (or internal)
API?
</p>
<p>
Naturally, I tried to apply the craftsmanship-oriented reasoning unilaterally.&nbsp;
Just make the public API so discoverable as to render the issue moot.&nbsp; But that
never totally satisfied me because I still liked my handy help screens and IntelliSense
info when consuming others' code.
</p>
<p>
And so I came to view XML doc comments on public methods as an exception.&nbsp; These,
after all, did not represent "comments."&nbsp; They came packaged with your deliverables
as your product.&nbsp; And I remain comfortable with that take today.
</p>
<h4>Generating Help More Efficiently
</h4>
<p>
Now, my nuanced evolved view doesn't automatically mean I'll resume laboriously hand-typing
XML comments.&nbsp; Early in my career, a sort of sad pride in this "work harder,
not smarter" approach characterized my development.&nbsp; But who has time for that
anymore?
</p>
<p>
Instead, with a little bit of investment in learning and tooling, you can do some
legitimately cool stuff.&nbsp; Let me take you through a nifty sequence of steps that
you may come to love.
</p>
<h4>GhostDoc Enterprise
</h4>
<p>
First up, take a look at <a href="http://submain.com/download/ghostdoc/enterprise/" target="_blank">the
GhostDoc Enterprise offering</a>.&nbsp;&nbsp;&nbsp; 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.&nbsp; Poking through
all that alone will probably take some time out of your day.&nbsp; You should download
and play with the product.
</p>
<p>
Once you are done with that, though, consider how you might get more efficient at
beefing up your API.&nbsp; For the rest of this post, I will use as an example <a href="https://github.com/erikdietrich/ChessTDD" target="_blank">my
Chess TDD project</a>.&nbsp; I use this as a toy codebase for all kinds of demos.
</p>
<p>
I never commented this codebase, nor did I generate any kind of documentation for
it.&nbsp; Why?&nbsp; I intended it solely as a teaching tool for test-driven development,
and never packaged it for others' consumption.&nbsp; Let's change that today.
</p>
<h4>Adding Comments
</h4>
<p>
Armed with GhostDoc enterprise, I will first generate some comments.&nbsp; The <a href="https://github.com/erikdietrich/ChessTDD/blob/master/Chess/Board.cs" target="_blank">Board</a> class
makes a likely candidate since that offers theoretical users the most value.
</p>
<p>
First up, I need to add XML doc comments to the file.&nbsp; I can do this by right
clicking in the file, and selecting "Document Type" from the GhostDoc Enterprise context
menu.&nbsp; Here's what the result looks like.
</p>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-1_2.png" rel="lightbox"><img title="blog-generate-docs-from-your-build-1" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="blog-generate-docs-from-your-build-1" src="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-1_thumb.png" width="640" height="439"></a>
</p>
<p>
The default template offers a pretty smart guess at intent, based on good variable
naming.&nbsp; 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.&nbsp;
But still, you probably want to take a human pass through, checking and tweaking where
needed.
</p>
<h4>Building Help Documentation
</h4>
<p>
All right.&nbsp; With comments in place for the public facing API of my little project,
we can move on to the actual documentation.&nbsp; Again, easy enough.&nbsp; Select
"Tools -&gt; GhostDoc Enterprise -&gt; Build Help Documentation" from the main menu.&nbsp;
You'll see this screen.
</p>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-2_2.png" rel="lightbox"><img title="blog-generate-docs-from-your-build-2" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="blog-generate-docs-from-your-build-2" src="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-2_thumb.png" width="640" height="453"></a>
</p>
<p>
Notice that you have a great deal of control over the particulars.&nbsp; Going into
detail here is beyond the scope of my post, but you can certainly play around.&nbsp;
I'll take the defaults and build a CHM help file.&nbsp; Once I click "OK", here's
what I see (once I go to the board class).
</p>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-3_2.png" rel="lightbox"><img title="blog-generate-docs-from-your-build-3" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="blog-generate-docs-from-your-build-3" src="http://submain.com/blog/content/binary/Open-Live-Writer/Generate-Documentation-from-Your-Build_CDB/blog-generate-docs-from-your-build-3_thumb.png" width="638" height="480"></a>
</p>
<p>
Pretty slick, huh?&nbsp; Seriously.&nbsp; With just a few clicks, you get intelligently
commented public methods and a professional-looking help file.&nbsp; (You can also
have this as web-style documentation if you want).&nbsp; 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.
</p>
<h4>Do It From the Build
</h4>
<p>
Only one bit of automation remains at this point.&nbsp; And that's the generation
of this documentation from the build.&nbsp; Fortunately, GhostDoc Enterprise makes
that simple as well.
</p>
<p>
Any build system worth its salt will, of course, let you hook command line invocations
into your build.&nbsp; GhostDoc Enterprise offers one up for just this occasion.&nbsp;
You can read <a href="http://support.submain.com/kb/a45/ghostdoc-enterprise-command-line-parameters.aspx" target="_blank">a
succinct guide on that right here</a>.&nbsp; With a single command, you can point
it at your solution, a help configuration, and a project configuration, and generate
the help file.&nbsp; Putting it where you want is then easy enough.
</p>
<p>
Tying this in with an automated build or CI setup really ties everything together,
including the theme of this post.&nbsp; 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.
</p>
<p>
<a style="font-size: 1.2em; line-height: 1.5" href="http://submain.com/ghostdoc/video/?skipto=intro" target="_blank">Learn
more about how GhostDoc can help simplify your XML Comments, produce and maintain
quality help documentation.</a>
</p>
<h4>About the Author
</h4>
<h5>Erik Dietrich
</h5>
<p>
I'm a passionate software developer and active blogger. Read about me at <a href="http://www.daedtech.com/additional-information/about" target="_blank">my
site</a>. <a href="http://submain.com/blog/CategoryView,category,ErikDietrich.aspx" target="_blank">View
all posts by Erik Dietrich</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=44e0ff6c-06ae-479f-9d48-c369ffbb0e2d" />http://submain.com/blog/CommentView,guid,44e0ff6c-06ae-479f-9d48-c369ffbb0e2d.aspxArticlesDocumentationErikDietrichGhostDochttp://submain.com/blog/Trackback.aspx?guid=4a1030a7-db5c-4a7f-9283-e6128255adechttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,4a1030a7-db5c-4a7f-9283-e6128255adec.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,4a1030a7-db5c-4a7f-9283-e6128255adec.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=4a1030a7-db5c-4a7f-9283-e6128255adec

Released: GhostDoc v5.3 updatehttp://submain.com/blog/PermaLink,guid,4a1030a7-db5c-4a7f-9283-e6128255adec.aspxhttp://submain.com/blog/ReleasedGhostDocV53Update.aspx
Fri, 16 Sep 2016 16:30:00 GMT<p>
Version 5.3 of GhostDoc is a maintenance update for the v5.0 users:
</p>
<ul>
<li>
Added full support for string interpolation in C# and VB parsers
<li>
Added support for "arrow functions" in JavaScript parser
<li>
Fixed "File is not part of a solution" issue when loading projects
<li>
(Pro) (Ent) Added IsAbstract property to CurrentCodeElement in the T4 templates
<li>
Improved exception documentation - now the type name in a nameof() parameter is added
as part of the generated documentation template
<li>
(Ent) Fixed iue when using &lt;section&gt; along with &lt;code&gt; elements in an
.aml file</li>
</ul>
<p>
For the complete list of changes, please see <a href="http://support.submain.com/kb/a42/whats-new-in-ghostdoc-v5.aspx" target="_blank">What's
New in GhostDoc v5</a>
</p>
<p>
For overview of the v5.0 features, visit <a href="http://submain.com/blog/ReleasedGhostDocV50.aspx" target="_blank">Overview
of GhostDoc v5.0 Features</a>
</p>
<p>
Download the new build at <a href="http://submain.com/download/ghostdoc/">http://submain.com/download/ghostdoc/</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=4a1030a7-db5c-4a7f-9283-e6128255adec" />http://submain.com/blog/CommentView,guid,4a1030a7-db5c-4a7f-9283-e6128255adec.aspxGhostDocNewsReleasesUpdateshttp://submain.com/blog/Trackback.aspx?guid=db2aa669-75b3-49f7-96ff-b3bb03ac1855http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,db2aa669-75b3-49f7-96ff-b3bb03ac1855.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,db2aa669-75b3-49f7-96ff-b3bb03ac1855.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=db2aa669-75b3-49f7-96ff-b3bb03ac1855

Think back to college (or high school, if applicable). Do you remember that
kid that would sit near the front of the class and gleefully point out that the professor
had accidentally omitted an apostrophe when writing notes on the white board?
Didn't you just love that kid? Yeah, me neither.

Fate imbues a small percentage of the population with a neurotic need to correct any
perceived mistakes made by anyone. XKCD immortalized this phenomenon with one
of its most famous cartoons, that declared, "someone
is wrong on the internet." For the rest of the population, however, this
tendency seems pedantic and, dare I say, unpleasant. Just let it go, man.
It doesn't matter that much.

I mention all of this to add context to the remainder of the post. I work as
a consultant and understand the need for diplomacy, tact, and choosing one's battles.
So, I do not propose something like care with spelling lightly. But I will propose
it, nonetheless.

Now I know what you're thinking. How can caring about spelling in code be anything
but pedantic? We're not talking about something being put together to impress
a wide audience, like a newspaper. In fact, we're not even talking about prose.
And code contains all sorts of abbreviations and encodings and whatnot.

Nevertheless, it matters. When English words occur in your code, spelling them
right matters. I'll use the rest of this post to make my case.

The IntelliSense Conundrum

If you use Visual Studio, no doubt you make heavy use of IntelliSense.
To expand, any IDE or text editor with autocomplete functionality qualifies for consideration
here. In either case, your tooling gives you a pretty substantial boost by suggesting
methods/variables/classes/etc based on what you have typed. It's like type-ahead
for code.

Now think of the effect a misspelling can have here, particularly near the beginning
of a word. Imagine implementing a method that would release resources and accidentally
typing Colse instead of Close.
Now imagine consuming that method. If you're used to exploring APIs and available
methods with auto-complete, you might type, "Clo", pause, and see no matching methods.
You might then conclude, "hey, no call to Close needed!"

In all likelihood, such an error would result in a few minutes of head-scratching
and then the right call. But even if that's the worst of it, that's still not
great. And it will happen each and every time someone uses your code.

Other Manual Typing Errors

The scope of this particular issue goes beyond auto-complete functionality.
Perhaps you lack that functionality in your environment, or perhaps you simply don't
use it much. In that case, you'll be hand typing your code.

Now, imagine hand typing the call above to a close method. Do you instinctively
type "Colse" or do you instinctively type "Close?" So what do you think will
happen?

You'll expect the call to be Close and you'll type that. Then, you'll stare
in disbelief for a moment at the compiler message. You'll probably do a clean
and rebuild. You'll stare again for a while and squint. Then, finally,
you'll smack your forehead, realize the problem, and silently berate the person who
misspelled the method name.

Again, the impact remains the same. Most likely this creates only friction and
annoyance. Every now and then, it may trigger a thoroughly incorrect use of
a library or API.

Anchoring Effect

Moving away from the theme of confusion when using a declared member, consider the
declaration itself. During the use of a variable/method/class/etc, you must
spell it right before the compiler allows you to proceed (assuming a strongly typed
language). With the original declaration, however, you have the freedom to spell
things wrong to your heart's content. When you do this, the original copy holds
the error.

That first misspelling allows for easy correction. Same goes when you've used
it only a time or two. But as usage grows and spreads throughout the codebase,
the fix becomes more and more of a chore. Before long (and without easy refactoring
tools), the chore becomes more than anyone feels like tackling, and the error calcifies
in place.

Comprehension Confusion

Let's switch gears again and consider the case of a maintenance programmer reading
for comprehension. After all, programmers do a whole lot more reading of code
than they do modification of it. So, a casual read is a likely situation.

Spelling errors cloud comprehension. A simple transposition of characters or
a common error, such as referring to a "dependency" do not present an insurmountable
problem. But a truly mangled word can leave readers scratching their heads and
wondering what the code actually means, almost as if you'd left some kind of brutal
Hungarian notation in there.

Taking the time to get the spelling right ensures that anyone maintaining the code
will not have this difficulty. Code is hard enough to understand, as-is, without
adding unforced errors to the mix.

The Embarrassment Factor

And, finally, there's the embarrassment factor. And I don't mean the embarrassment
of your coworkers saying, "wow, that guy doesn't know how to spell!" I'm talking
about the embarrassment factor for the team.

Think of new developers hiring on or transferring into the group. They're going
to take a look at the code and draw conclusions, about your team. Software developers
tend to have exacting, detail-oriented minds, and they tend to notice mistakes.
Having a bunch of spelling mistakes in common words makes it appear either that the
team doesn't know how to spell or that it has a sloppy approach. Neither of
those is great.

But also keep in mind that what happens in the code doesn't always stay in the code.
Bits of the code you write might appear on team dashboards, build reports, unit test
run outputs, etc. People from outside of the team may be examining acceptance
tests and the like. And, you may have end-user documentation generated automatically
using your code (i.e. if you make developer tools or APIs). Do you really want
the documentation you hand to your customers to contain embarrassing mistakes?

It's Easy to Get Right

At this point, I'm finished with the supply of arguments for making the case.
I've laid these out.

But, by way of closing words, I'd like to comment on what might be the biggest shame
of the whole thing. Purging your code of spelling errors doesn't require you
to be an expert speller. It doesn't require you to copy source code into MS
Word or something and run a check. You have tools at your disposal that will
do this for you, right
in your IDE. All you need to do is turn them on.

I recommend that you do this immediately. It's easy, unobtrusive, and offers
only upside. And not only will you excise spelling mistakes from your code --
you'll also prevent that annoying kid in the front of the class from bothering you
about stuff you don't have time for.

About the Author

Erik Dietrich

What's in a Name? Spelling Matters in Codehttp://submain.com/blog/PermaLink,guid,db2aa669-75b3-49f7-96ff-b3bb03ac1855.aspxhttp://submain.com/blog/WhatsInANameSpellingMattersInCode.aspx
Wed, 14 Sep 2016 15:06:00 GMT<p>
Think back to college (or high school, if applicable).&nbsp; Do you remember that
kid that would sit near the front of the class and gleefully point out that the professor
had accidentally omitted an apostrophe when writing notes on the white board?&nbsp;
Didn't you just love that kid?&nbsp; Yeah, me neither.
</p>
<p>
Fate imbues a small percentage of the population with a neurotic need to correct any
perceived mistakes made by anyone.&nbsp; XKCD immortalized this phenomenon with one
of its most famous cartoons, that declared, "<a href="https://xkcd.com/386/" target="_blank">someone
is wrong on the internet</a>."&nbsp; For the rest of the population, however, this
tendency seems pedantic and, dare I say, unpleasant.&nbsp; Just let it go, man.&nbsp;
It doesn't matter that much.
</p>
<p>
I mention all of this to add context to the remainder of the post.&nbsp; I work as
a consultant and understand the need for diplomacy, tact, and choosing one's battles.&nbsp;
So, I do not propose something like care with spelling lightly.&nbsp; But I will propose
it, nonetheless.
</p>
<p>
Now I know what you're thinking.&nbsp; How can caring about spelling in code be anything
but pedantic?&nbsp; We're not talking about something being put together to impress
a wide audience, like a newspaper.&nbsp; In fact, we're not even talking about prose.&nbsp;
And code contains all sorts of abbreviations and encodings and whatnot.
</p>
<p>
Nevertheless, it matters.&nbsp; When English words occur in your code, spelling them
right matters.&nbsp; I'll use the rest of this post to make my case.
</p>
<h4>The IntelliSense Conundrum
</h4>
<p>
If you use Visual Studio, no doubt you make heavy use of <a href="https://msdn.microsoft.com/en-us/library/hcw1s69b.aspx" target="_blank">IntelliSense</a>.&nbsp;
To expand, any IDE or text editor with autocomplete functionality qualifies for consideration
here.&nbsp; In either case, your tooling gives you a pretty substantial boost by suggesting
methods/variables/classes/etc based on what you have typed.&nbsp; It's like type-ahead
for code.
</p>
<p>
Now think of the effect a misspelling can have here, particularly near the beginning
of a word.&nbsp; Imagine implementing a method that would release resources and accidentally
typing <font style="background-color: #ffff00">Colse</font> instead of <font style="background-color: #ffff00">Close</font>.&nbsp;
Now imagine consuming that method.&nbsp; If you're used to exploring APIs and available
methods with auto-complete, you might type, "Clo", pause, and see no matching methods.&nbsp;
You might then conclude, "hey, no call to Close needed!"
</p>
<p>
In all likelihood, such an error would result in a few minutes of head-scratching
and then the right call.&nbsp; But even if that's the worst of it, that's still not
great.&nbsp; And it will happen each and every time someone uses your code.
</p>
<h4>Other Manual Typing Errors
</h4>
<p>
The scope of this particular issue goes beyond auto-complete functionality.&nbsp;
Perhaps you lack that functionality in your environment, or perhaps you simply don't
use it much.&nbsp; In that case, you'll be hand typing your code.
</p>
<p>
Now, imagine hand typing the call above to a close method.&nbsp; Do you instinctively
type "Colse" or do you instinctively type "Close?"&nbsp; So what do you think will
happen?
</p>
<p>
You'll expect the call to be Close and you'll type that.&nbsp; Then, you'll stare
in disbelief for a moment at the compiler message.&nbsp; You'll probably do a clean
and rebuild.&nbsp; You'll stare again for a while and squint.&nbsp; Then, finally,
you'll smack your forehead, realize the problem, and silently berate the person who
misspelled the method name.
</p>
<p>
Again, the impact remains the same.&nbsp; Most likely this creates only friction and
annoyance.&nbsp; Every now and then, it may trigger a thoroughly incorrect use of
a library or API.
</p>
<h4>Anchoring Effect
</h4>
<p>
Moving away from the theme of confusion when using a declared member, consider the
declaration itself.&nbsp; During the use of a variable/method/class/etc, you must
spell it right before the compiler allows you to proceed (assuming a strongly typed
language).&nbsp; With the original declaration, however, you have the freedom to spell
things wrong to your heart's content.&nbsp; When you do this, the original copy holds
the error.
</p>
<p>
That first misspelling allows for easy correction.&nbsp; Same goes when you've used
it only a time or two.&nbsp; But as usage grows and spreads throughout the codebase,
the fix becomes more and more of a chore.&nbsp; Before long (and without easy refactoring
tools), the chore becomes more than anyone feels like tackling, and the error calcifies
in place.
</p>
<p>
Your unaddressed spelling mistake today makes fixes more difficult tomorrow.
</p>
<h4>Comprehension Confusion
</h4>
<p>
Let's switch gears again and consider the case of a maintenance programmer reading
for comprehension.&nbsp; After all, programmers do a whole lot more reading of code
than they do modification of it.&nbsp; So, a casual read is a likely situation.
</p>
<p>
Spelling errors cloud comprehension.&nbsp; A simple transposition of characters or
a common error, such as referring to a "dependency" do not present an insurmountable
problem.&nbsp; But a truly mangled word can leave readers scratching their heads and
wondering what the code actually means, almost as if you'd left some kind of brutal
Hungarian notation in there.
</p>
<p>
Taking the time to get the spelling right ensures that anyone maintaining the code
will not have this difficulty.&nbsp; Code is hard enough to understand, as-is, without
adding unforced errors to the mix.
</p>
<h4>The Embarrassment Factor
</h4>
<p>
And, finally, there's the embarrassment factor.&nbsp; And I don't mean the embarrassment
of your coworkers saying, "wow, that guy doesn't know how to spell!"&nbsp; I'm talking
about the embarrassment factor for the team.
</p>
<p>
Think of new developers hiring on or transferring into the group.&nbsp; They're going
to take a look at the code and draw conclusions, about your team.&nbsp; Software developers
tend to have exacting, detail-oriented minds, and they tend to notice mistakes.&nbsp;
Having a bunch of spelling mistakes in common words makes it appear either that the
team doesn't know how to spell or that it has a sloppy approach.&nbsp; Neither of
those is great.
</p>
<p>
But also keep in mind that what happens in the code doesn't always stay in the code.&nbsp;
Bits of the code you write might appear on team dashboards, build reports, unit test
run outputs, etc.&nbsp; People from outside of the team may be examining acceptance
tests and the like.&nbsp; And, you may have end-user documentation generated automatically
using your code (i.e. if you make developer tools or APIs).&nbsp; Do you really want
the documentation you hand to your customers to contain embarrassing mistakes?
</p>
<h4>It's Easy to Get Right
</h4>
<p>
At this point, I'm finished with the supply of arguments for making the case.&nbsp;
I've laid these out.
</p>
<p>
But, by way of closing words, I'd like to comment on what might be the biggest shame
of the whole thing.&nbsp; Purging your code of spelling errors doesn't require you
to be an expert speller.&nbsp; It doesn't require you to copy source code into MS
Word or something and run a check.&nbsp; You have tools at your disposal that will
do this for you, <a href="http://submain.com/ghostdoc/video/?skipto=spellcheck" target="_blank">right
in your IDE</a>.&nbsp; All you need to do is turn them on.
</p>
<p>
I recommend that you do this immediately.&nbsp; It's easy, unobtrusive, and offers
only upside.&nbsp; And not only will you excise spelling mistakes from your code --
you'll also prevent that annoying kid in the front of the class from bothering you
about stuff you don't have time for.
</p>
<p>
<a style="font-size: 1.2em; line-height: 1.5" href="http://submain.com/ghostdoc/video/?skipto=spellcheck" target="_blank">Learn
more about GhostDoc's truly <i>source code</i> spell checker and eliminate embarrassing
typos in your apps and documentation before you ship them.</a>
</p>
<h4>About the Author
</h4>
<h5>Erik Dietrich
</h5>
<p>
I'm a passionate software developer and active blogger. Read about me at <a href="http://www.daedtech.com/additional-information/about" target="_blank">my
site</a>. <a href="http://submain.com/blog/CategoryView,category,ErikDietrich.aspx" target="_blank">View
all posts by Erik Dietrich</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=db2aa669-75b3-49f7-96ff-b3bb03ac1855" />http://submain.com/blog/CommentView,guid,db2aa669-75b3-49f7-96ff-b3bb03ac1855.aspxArticlesDocumentationErikDietrichGhostDochttp://submain.com/blog/Trackback.aspx?guid=79d6fc83-74c9-441b-931f-f4ee352bf8d7http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,79d6fc83-74c9-441b-931f-f4ee352bf8d7.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,79d6fc83-74c9-441b-931f-f4ee352bf8d7.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=79d6fc83-74c9-441b-931f-f4ee352bf8d7

Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming
experience came in college. A course called "Intro to C++" got us acquainted
with arrays, loops, data structures and the like. Given its introductory nature,
this class did not pose a particularly serious challenge (that would come later).
So, with all of the maturity generally possessed by 18 year olds, we had a bit of
fun.

I recall contests to see how much application logic we could jam into the loop conditions,
and contests to see how much code could be packed onto one line. These sorts
of scavenger hunt activities obviously produced dense, illegible code. But then,
that was kind of the point.

Beyond these silly hijinks, however, a culture of code illegibility permeated this
(and, I would learn later) other campuses. Professors nominally encouraged code
readability. After all, such comments facilitated partial credit in the event
of a half-baked homework submission. But, even still, the mystique of the ingenious
but inscrutable algorithm pervaded the culture both for students and faculty.
I had occasion to see code written by various professors, and I noticed no comments
that I can recall.

Professionalism via Thoroughness

When I graduated from college, I carried this culture with me. But not for long.
I took a job where I spent most of my days working on driver and kernel module programming.
There, I noticed that the grizzled veterans to whom I looked up meticulously documented
their code. Above each function sat a neat, orderly comment containing information
about its purpose, parameters, return values, and modification history.

This, I realized, was how professionals conducted themselves. I was hooked.
Fresh out of college, and looking to impress the world, I sought to distinguish myself
from my undisciplined student ways. This decision ushered in a period of many
years in which I documented my code with near religious fervor.

My habit included, obviously, the method headers that I emulated. But on top
of that, I added class headers and regularly peppered my code with line comments that
offered such wisdom as "increment the loop counter until the end of the array."
(Okay, probably not that bad, but you get the idea). I also wrote lengthy readme
documents for posterity and maintenance programmers alike. My professionalism
knew no bounds.

Clean Code as Plot Twist

Eventually, I moved on from that job, but carried my habits with me. I wrote
different code for different purposes in different domains, but stayed consistent
in my commenting diligence. This I wore as a badge of pride.

While I was growing in my career, I started to draw inspiration from the clean code
movement. I began to write unit tests, I practiced the SOLID
principles, I watched Uncle Bob talks, made my methods small, and sought to convince
others to do the same. Through it all, I continued to write comments.

But then something disconcerting happened. In the clean code circles I followed
and aspired to, I started to see posts
like this one. In it, the author had written extensively about comments
as a code smell.

Comments are a great example of something that seems like a Good Thing, but turn out
to cause more harm than good.

For a while, I dismissed this heresy as an exception to the general right-thinking
of the clean code movement. I ignored it. But it nagged at me nonetheless,
and eventually, I had to confront it.

When I finally did, I realized that I had continued to double down on a practice simply
because I had done it for so long. In other words, the extensive commenting
represented a ritual of diligence rather than something in which I genuinely saw value.

Down with Comments

Once the floodgates had opened, I did an about-face. I completely stopped writing
comments of any sort whatsoever, unless it was part of the standard of the group I
was working with.

The clean coder rationale flooded over me and made sense. Instead of writing
inline comments, make the code self-documenting. Instead of comments in general,
write unit and acceptance tests that describe the desired behaviors. If you
need to explain in English what your code does, you have failed to explain with your
code.

Probably most compelling of all, though, was the tendency that I'd noticed for comments
to rot. I cannot begin to estimate how many times I dutifully wrote comments
about a method, only to return a year later and see that the method had been changed
while the comments had not. My once-helpful comments now lied to anyone reading
them, making me look either negligent or like an idiot. Comments represented
duplication of knowledge, and duplication of knowledge did what it always does: gets
out of sync.

My commenting days were over.

Best of All Worlds

That still holds true to this day. I do not comment my code in the traditional
sense. Instead, I write copious amounts of unit, integration and acceptance
tests to demonstrate intent. And, where necessary and valuable, I generate documentation.

Let's not confuse documentation and commenting. Commenting code targets maintenance
programmers and team members as the intended audience. Documenting, on the other
hand, targets external consumers. For instance, if I maintained a library at
a large organization, and other teams used that library, they would be external consumers
rather than team members. In effect, they constitute customers.

If we think of API consumers as customers, then generating examples and documentation
becomes critically important. In a sense, this activity is the equivalent of
designing an intuitive interface for end-users of a GUI application. They need
to understand how to quickly and effectively make the most of what you offer.

So if you're like me -- if you believe firmly in the tenets of the clean code movement
-- understand that comments and documentation are not the same thing. Also understand
that documentation has real, business value and occupies an important role in what
we do. Documentation may take the form of actual help documents, files, or XML-doc
style comments that appear in IntelliSense implementations.

To achieve the best of all worlds, avoid duplication. Make publishing documentation
and examples a part of your process and, better yet, automate these activities.
Your code will stay clean and maintainable and your API users will be well-informed
and empowered to use your code.

About the Author

Erik Dietrich

Comments in Clean Code? Think Documentationhttp://submain.com/blog/PermaLink,guid,79d6fc83-74c9-441b-931f-f4ee352bf8d7.aspxhttp://submain.com/blog/CommentsInCleanCodeThinkDocumentation.aspx
Thu, 18 Aug 2016 15:45:00 GMT<p>
Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming
experience came in college.&nbsp; A course called "Intro to C++" got us acquainted
with arrays, loops, data structures and the like.&nbsp; Given its introductory nature,
this class did not pose a particularly serious challenge (that would come later).&nbsp;
So, with all of the maturity generally possessed by 18 year olds, we had a bit of
fun.
</p>
<p>
I recall contests to see how much application logic we could jam into the loop conditions,
and contests to see how much code could be packed onto one line.&nbsp; These sorts
of scavenger hunt activities obviously produced dense, illegible code.&nbsp; But then,
that was kind of the point.
</p>
<p>
Beyond these silly hijinks, however, a culture of code illegibility permeated this
(and, I would learn later) other campuses.&nbsp; Professors nominally encouraged code
readability.&nbsp; After all, such comments facilitated partial credit in the event
of a half-baked homework submission.&nbsp; But, even still, the mystique of the ingenious
but inscrutable algorithm pervaded the culture both for students and faculty.&nbsp;
I had occasion to see code written by various professors, and I noticed no comments
that I can recall.
</p>
<h4>Professionalism via Thoroughness
</h4>
<p>
When I graduated from college, I carried this culture with me.&nbsp; But not for long.&nbsp;
I took a job where I spent most of my days working on driver and kernel module programming.&nbsp;
There, I noticed that the grizzled veterans to whom I looked up meticulously documented
their code.&nbsp; Above each function sat a neat, orderly comment containing information
about its purpose, parameters, return values, and modification history.
</p>
<p>
This, I realized, was how professionals conducted themselves.&nbsp; I was hooked.&nbsp;
Fresh out of college, and looking to impress the world, I sought to distinguish myself
from my undisciplined student ways.&nbsp; This decision ushered in a period of many
years in which I documented my code with near religious fervor.
</p>
<p>
My habit included, obviously, the method headers that I emulated.&nbsp; But on top
of that, I added class headers and regularly peppered my code with line comments that
offered such wisdom as "increment the loop counter until the end of the array."&nbsp;
(Okay, probably not that bad, but you get the idea).&nbsp; I also wrote lengthy readme
documents for posterity and maintenance programmers alike.&nbsp; My professionalism
knew no bounds.
</p>
<h4>Clean Code as Plot Twist
</h4>
<p>
Eventually, I moved on from that job, but carried my habits with me.&nbsp; I wrote
different code for different purposes in different domains, but stayed consistent
in my commenting diligence.&nbsp; This I wore as a badge of pride.
</p>
<p>
While I was growing in my career, I started to draw inspiration from the clean code
movement.&nbsp; I began to write unit tests, I practiced the <a href="https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)" target="_blank">SOLID
principles</a>, I watched Uncle Bob talks, made my methods small, and sought to convince
others to do the same.&nbsp; Through it all, I continued to write comments.
</p>
<p>
But then something disconcerting happened.&nbsp; In the clean code circles I followed
and aspired to, I started to see <a href="http://memeagora.blogspot.co.uk/2008/11/comments-code-smell.html" target="_blank">posts
like this one</a>.&nbsp; In it, the author had written extensively about comments
as a code smell.
</p>
<p>
Comments are a great example of something that seems like a Good Thing, but turn out
to cause more harm than good.
</p>
<p>
For a while, I dismissed this heresy as an exception to the general right-thinking
of the clean code movement.&nbsp; I ignored it.&nbsp; But it nagged at me nonetheless,
and eventually, I had to confront it.
</p>
<p>
When I finally did, I realized that I had continued to double down on a practice simply
because I had done it for so long.&nbsp; In other words, the extensive commenting
represented a ritual of diligence rather than something in which I genuinely saw value.
</p>
<h4>Down with Comments
</h4>
<p>
Once the floodgates had opened, I did an about-face.&nbsp; I completely stopped writing
comments of any sort whatsoever, unless it was part of the standard of the group I
was working with.
</p>
<p>
The clean coder rationale flooded over me and made sense.&nbsp; Instead of writing
inline comments, make the code self-documenting.&nbsp; Instead of comments in general,
write unit and acceptance tests that describe the desired behaviors.&nbsp; If you
need to explain in English what your code does, you have failed to explain with your
code.
</p>
<p>
Probably most compelling of all, though, was the tendency that I'd noticed for comments
to rot.&nbsp; I cannot begin to estimate how many times I dutifully wrote comments
about a method, only to return a year later and see that the method had been changed
while the comments had not.&nbsp; My once-helpful comments now lied to anyone reading
them, making me look either negligent or like an idiot.&nbsp; Comments represented
duplication of knowledge, and duplication of knowledge did what it always does: gets
out of sync.
</p>
<p>
My commenting days were over.
</p>
<h4>Best of All Worlds
</h4>
<p>
That still holds true to this day.&nbsp; I do not comment my code in the traditional
sense.&nbsp; Instead, I write copious amounts of unit, integration and acceptance
tests to demonstrate intent.&nbsp; And, where necessary and valuable, I generate documentation.
</p>
<p>
Let's not confuse documentation and commenting.&nbsp; Commenting code targets maintenance
programmers and team members as the intended audience.&nbsp; Documenting, on the other
hand, targets external consumers.&nbsp; For instance, if I maintained a library at
a large organization, and other teams used that library, they would be external consumers
rather than team members.&nbsp; In effect, they constitute customers.
</p>
<p>
If we think of API consumers as customers, then generating examples and documentation
becomes critically important.&nbsp; In a sense, this activity is the equivalent of
designing an intuitive interface for end-users of a GUI application.&nbsp; They need
to understand how to quickly and effectively make the most of what you offer.
</p>
<p>
So if you're like me -- if you believe firmly in the tenets of the clean code movement
-- understand that comments and documentation are not the same thing.&nbsp; Also understand
that documentation has real, business value and occupies an important role in what
we do.&nbsp; Documentation may take the form of actual help documents, files, or <a href="http://submain.com/ghostdoc" target="_blank">XML-doc
style comments</a> that appear in IntelliSense implementations.
</p>
<p>
To achieve the best of all worlds, avoid duplication.&nbsp; Make publishing documentation
and examples a part of your process and, better yet, automate these activities.&nbsp;
Your code will stay clean and maintainable and your API users will be well-informed
and empowered to use your code.
</p>
<p>
<a style="font-size: 1.2em; line-height: 1.5" href="http://submain.com/ghostdoc" target="_blank">Learn
more about how GhostDoc can help simplify your XML Comments, produce and maintain
quality help documentation.</a>
</p>
<h4>About the Author
</h4>
<h5>Erik Dietrich
</h5>
<p>
I'm a passionate software developer and active blogger. Read about me at <a href="http://www.daedtech.com/additional-information/about" target="_blank">my
site</a>. <a href="http://submain.com/blog/CategoryView,category,ErikDietrich.aspx" target="_blank">View
all posts by Erik Dietrich</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=79d6fc83-74c9-441b-931f-f4ee352bf8d7" />http://submain.com/blog/CommentView,guid,79d6fc83-74c9-441b-931f-f4ee352bf8d7.aspxArticlesDocumentationErikDietrichGhostDochttp://submain.com/blog/Trackback.aspx?guid=dbbf3a5d-3851-4a4e-a4e0-7a222d52c62chttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,dbbf3a5d-3851-4a4e-a4e0-7a222d52c62c.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,dbbf3a5d-3851-4a4e-a4e0-7a222d52c62c.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=dbbf3a5d-3851-4a4e-a4e0-7a222d52c62c

Version 5.2 of GhostDoc is a minor feature release for the v5.0 users includes:

Support for Visual Studio 2015 Update 3

Fixes for the latest ASP.NET Core projects

GhostDoc now treats underscore as a delimiter to improve summary generation for underscore
delimited identifiers

Version 5.1 of GhostDoc is a maintenance release for the v5.0 users; includes minor
enhancements and number of important bug fixes. Many of the fixes are relevant to
the Visual Studio 2015 environment, so while everyone will benefit from this update,
it is highly recommended for the Visual Studio 2015 users.

Released: GhostDoc v5.1 updatehttp://submain.com/blog/PermaLink,guid,3edbd2c9-a909-486e-8e18-965793fa6d42.aspxhttp://submain.com/blog/ReleasedGhostDocV51Update.aspx
Sat, 06 Feb 2016 03:33:00 GMT<p>
Version 5.1 of GhostDoc is a maintenance release for the v5.0 users; includes minor
enhancements and number of important bug fixes. Many of the fixes are relevant to
the Visual Studio 2015 environment, so while everyone will benefit from this update,
it is highly recommended for the Visual Studio 2015 users.
</p>
<p>
For the complete list of changes, please see <a href="http://support.submain.com/kb/a42/whats-new-in-ghostdoc-v5.aspx">http://support.submain.com/kb/a42/whats-new-in-ghostdoc-v5.aspx</a>
</p>
<p>
For overview of the v5.0 features, visit <a href="http://submain.com/blog/ReleasedGhostDocV50.aspx">http://submain.com/blog/ReleasedGhostDocV50.aspx</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=3edbd2c9-a909-486e-8e18-965793fa6d42" />http://submain.com/blog/CommentView,guid,3edbd2c9-a909-486e-8e18-965793fa6d42.aspxGhostDocReleasesUpdateshttp://submain.com/blog/Trackback.aspx?guid=5ad25e66-488e-4a5e-9628-8c92667d7675http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,5ad25e66-488e-4a5e-9628-8c92667d7675.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,5ad25e66-488e-4a5e-9628-8c92667d7675.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=5ad25e66-488e-4a5e-9628-8c92667d7675

Note to GhostDoc Pro v4 users: The v4 licenses
won’t work with the v5. We have sent out the v5 license codes to users with License
Protection and active Software Assurance subscription. If you have not received or
misplaced your new license, you can retrieve it on the My
Account page. See more information at the bottom of this post.

Both Pro and Enterprise editions of GhostDoc in version 5 introduce Documentation
Quality hints in Visual Studio editor; Documentation Management assistance - find
auto-generated comments, edit or remove the bulk created docs; identify and fix comments
that are missing, out of sync or can be copied from base class; mark generated XML
comments as auto-generated and "to be edited". The v5 also includes multiple Help
documentation themes and layouts to choose from.

The free version of GhostDoc has been re-branded as GhostDoc Community Edition and
adds general improvements, limited generation of CHM help documentation as well as
the means to find auto-generated comments.

Option to have the default summary text focused and selected when using Document This
command - allows to edit/override the summary quickly

Exclude from Documentation action – marks a member with a tag to
exclude it from the help documentation

Hide/Show Comments feature – an easy way to expand/collapse documentation
comments to minimize the XML Comments footprint in the Visual Studio code editor

New Summary Override table in Options - configure predefined summaries
for specific member or type names instead of auto-generated

A basic Build Documentation feature is now available in the Community Edition of GhostDoc
– while quite limited and watermarked, yet allows to produce simple CHM help documentation
for personal use without paying for the commercial version

This new feature provides real-time visual hints in the Visual
Studio Editor window to highlight members which have documentation issues that require
attention.

The following documentation hint actions included with this
release make it very easy to maintain the documentation quality:

Documentation Maintenance

This feature will help you identify missing
documentation, find auto-generated XML comments, maintain your documentation, and
keep it up to date. Once these are found, GhostDoc provides the tools to edit or remove
the bulk created docs, add missing or fix the dated documentation – one by one or
as a batch. You can fine tune the search criteria and use your own template library
if yours is different from the built-in.

Find auto-generated docs and edit or remove them

Find and fix members that are missing documentation

Discover members that have parameters, return types, and type parameters out of sync
with the existing XML comments and fix the comments

Find members that can have XML docs copied from the base class

Find documentation that require editing

The Community Edition only allows to find auto-generated documentation
and not batch actions – only one action at a time.

Help Documentation Themes

In the v5 we are introducing theme support for the generated
help documentation and including two new themes, The
old help doc view preserved as the Classic theme. You can see the new theme preview
here - Flat
Gray (default) and Flat
Main.

The Enterprise Edition users can modify the existing themes
or create and deploy own help documentation themes – now easier than ever!

The Community Edition theme selection is limited to one – Classic.

Auto-generated doc and TODO 'Edit' attributes

The option to add
tag to XML comment is intended to provide an explicit flag that the comment has been
generated automatically.

The option to add a TODO comment “TODO Edit XML Comment Template for {member name}”
which in turn adds a TODO task into the Visual Studio Task List –> Comments as a reminder
for the auto-generated comment requires editing.

Both flags can be used as additional criteria for the documentation quality hints
and documentation management “Find auto-generated Documentation” feature. When generating
help documentation these flags are also accounted for – the flagged members can be
included, ignored or highlighted in the final docs.

Summary Override

The Summary Override table allows to configure predefined summaries for specific member
or type names to be used instead of the auto-generated. We ship some predefined summary
overrides and you are welcome to add your own. If you find a summary override that
the GhostDoc user community can benefit of, please submit
it to us to be reviewed for the inclusion.

Note to the GhostDoc Pro v4 users: The v4.x license codes won't work with
the v5.0. For users with License Protection and active Software Assurance subscription
we have sent out the v5.x license codes. If you have not received or misplaced your
new license, you can retrieve it on the My
Account page. Users without the License Protection or with expired Software Assurance
subscription will need to purchase the new version - currently we are not offering
upgrade path other than the Software Assurance subscription. For information about
the upgrade protection see our Software
Assurance and Support - Renewal / Reinstatement Terms

Released: GhostDoc v5.0http://submain.com/blog/PermaLink,guid,5ad25e66-488e-4a5e-9628-8c92667d7675.aspxhttp://submain.com/blog/ReleasedGhostDocV50.aspx
Tue, 24 Nov 2015 04:02:00 GMT<div class="messageInfo"><strong>Note to GhostDoc Pro v4 users</strong>: The v4 licenses
won’t work with the v5. We have sent out the v5 license codes to users with License
Protection and active Software Assurance subscription. If you have not received or
misplaced your new license, you can retrieve it on the <a href="http://submain.com/MyAccount/" target="_blank">My
Account</a> page. See more information at the bottom of this post.
</div>
<p>
Both Pro and Enterprise editions of GhostDoc in version 5 introduce Documentation
Quality hints in Visual Studio editor; Documentation Management assistance - find
auto-generated comments, edit or remove the bulk created docs; identify and fix comments
that are missing, out of sync or can be copied from base class; mark generated XML
comments as auto-generated and "to be edited". The v5 also includes multiple Help
documentation themes and layouts to choose from.
</p>
<p>
The free version of GhostDoc has been re-branded as <strong>GhostDoc Community Edition</strong> and
adds general improvements, limited generation of CHM help documentation as well as
the means to find auto-generated comments.
</p>
<div style="float: right">
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_new_commands_2.png" rel="lightbox"><img title="GD_v5_new_commands" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_new_commands" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_new_commands_thumb.png" width="377" align="right" height="170"></a>
</p>
<p>
<em>The new menu commands</em>
</p>
</div>
<ul>
<li>
<strong>Documentation Quality Hints</strong> in Visual Studio editor
<li>
<strong>Documentation Maintenance</strong> - Find auto-generated comments - edit or
remove the bulk created docs
<li>
<strong>Documentation Maintenance</strong> - Identify and fix comments that are missing,
out of sync or can be copied from base class
<li>
<strong>Theme support</strong> for generated help documentation and new themes - <a href="http://submain.com/ghostdoc/samples/themes/flatgray/" target="_blank">Flat
Gray</a> and <a href="http://submain.com/ghostdoc/samples/themes/flatmain/" target="_blank">Flat
Main</a>
<li>
Official <strong>Visual Studio 2015 support</strong>
<li>
Options to add Auto-generated doc and TODO 'Edit' attributes
<li>
Option to have the default summary text focused and selected when using Document This
command - allows to edit/override the summary quickly
<li>
<strong>Exclude from Documentation action</strong> – marks a member with a tag to
exclude it from the help documentation
<li>
<strong>Hide/Show Comments feature</strong> – an easy way to expand/collapse documentation
comments to minimize the XML Comments footprint in the Visual Studio code editor
<li>
New <strong>Summary Override</strong> table in Options - configure predefined summaries
for specific member or type names instead of auto-generated
<li>
A basic Build Documentation feature is now available in the Community Edition of GhostDoc
– while quite limited and watermarked, yet allows to produce simple CHM help documentation
for personal use without paying for the commercial version</li>
</ul>
<p>
<font color="#000000">For the detailed list of v5.0 changes see <a href="http://support.submain.com/kb/a42/whats-new-in-ghostdoc-v5.aspx" target="_blank">What’s
New in GhostDoc v5</a>.</font>
</p>
<p>
<font color="#000000">To see new features by product edition see this page - <a href="http://submain.com/ghostdoc/editions/" target="_blank">http://submain.com/ghostdoc/editions/</a></font>
</p>
<p>
<font color="#000000"><strong>
<br>
Documentation Quality Hints</strong></font>
</p>
<p>
<font color="#000000">This new feature provides real-time visual hints in the Visual
Studio Editor window to highlight members which have documentation issues that require
attention.</font>
</p>
<p>
<img title="GD_v5_maint_hints" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_maint_hints" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_maint_hints_6.png" width="561" height="187">
</p>
<p>
<font color="#000000">The following documentation hint actions included with this
release make it very easy to maintain the documentation quality:</font>
</p>
<p>
<font color="#000000"><img title="GD_v5_maint_hints_list" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_maint_hints_list" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_maint_hints_list_3.png" width="338" height="142"></font>
</p>
<p>
<font color="#000000"><strong>
<br>
Documentation Maintenance</strong></font>
</p>
<p>
<font color="#000000">This feature will help you identify </font><font color="#000000">missing
documentation, find auto-generated XML comments, maintain your documentation, and
keep it up to date. Once these are found, GhostDoc provides the tools to edit or remove
the bulk created docs, add missing or fix the dated documentation – one by one or
as a batch. You can fine tune the search criteria and use your own template library
if yours is different from the built-in.</font>
</p>
<ul>
<li>
Find auto-generated docs and edit or remove them
<li>
Find and fix members that are missing documentation
<li>
Discover members that have parameters, return types, and type parameters out of sync
with the existing XML comments and fix the comments
<li>
Find members that can have XML docs copied from the base class
<li>
Find documentation that require editing</li>
</ul>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_maint_autogen_2.png" rel="lightbox"><img title="GD_v5_maint_autogen" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_maint_autogen" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_maint_autogen_thumb.png" width="632" height="121"></a>
</p>
<p>
<font color="#000000">The Community Edition only allows to find auto-generated documentation
and not batch actions – only one action at a time.</font>
</p>
<p>
<font color="#000000"><strong>
<br>
Help Documentation Themes </strong></font>
</p>
<p>
<font color="#000000">In the v5 we are introducing theme support for the generated
help documentation and including two new themes, </font><font color="#000000">The
old help doc view preserved as the Classic theme. You can see the new theme preview
here - <a href="http://submain.com/ghostdoc/samples/themes/flatgray/" target="_blank">Flat
Gray</a> (default) and <a href="http://submain.com/ghostdoc/samples/themes/flatmain/" target="_blank">Flat
Main</a>.</font>
</p>
<p>
<font color="#000000">The Enterprise Edition users can modify the existing themes
or create and deploy own help documentation themes – now easier than ever!</font>
</p>
<p>
<font color="#000000">The Community Edition theme selection is limited to one – Classic.</font>
</p>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_help_sample_2.png" rel="lightbox"><img title="GD_v5_help_sample" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_help_sample" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_help_sample_thumb.png" width="632" height="321"></a>
</p>
<p>
<strong>
<br>
Auto-generated doc and TODO 'Edit' attributes</strong>
</p>
<p>
The option to add
<autogeneratedoc />
tag to XML comment is intended to provide an explicit flag that the comment has been
generated automatically.
</p>
<p>
The option to add a TODO comment “TODO Edit XML Comment Template for {member name}”
which in turn adds a TODO task into the Visual Studio Task List –> Comments as a reminder
for the auto-generated comment requires editing.
</p>
<p>
<a href="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_autogen_todo_6.png" rel="lightbox"><img title="GD_v5_autogen_todo" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_autogen_todo" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_autogen_todo_thumb_1.png" width="381" height="101"></a>
</p>
<p>
Both flags can be used as additional criteria for the documentation quality hints
and documentation management “Find auto-generated Documentation” feature. When generating
help documentation these flags are also accounted for – the flagged members can be
included, ignored or highlighted in the final docs.
</p>
<p>
<strong>
<br>
Summary Override</strong>
</p>
<p>
The Summary Override table allows to configure predefined summaries for specific member
or type names to be used instead of the auto-generated. We ship some predefined summary
overrides and you are welcome to add your own. If you find a summary override that
the GhostDoc user community can benefit of, please <a href="http://submain.com/support/feedback" target="_blank">submit
it to us</a> to be reviewed for the inclusion.
</p>
<p>
<img title="GD_v5_summary_override" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="GD_v5_summary_override" src="http://submain.com/blog/content/binary/Open-Live-Writer/Released_15158/GD_v5_summary_override_3.png" width="404" height="172">
</p>
<p>
<strong></strong>
</p>
<p>
<strong>How do I try it?</strong>
</p>
<p>
Download the v5.0 at <a href="http://submain.com/download/ghostdoc/" target="_blank">http://submain.com/download/ghostdoc/</a>
</p>
<p>
<strong>
<br>
Feedback is what keeps us going!</strong>
</p>
<p>
Let us know what you think of the new version here - <a href="http://submain.com/support/feedback/" target="_blank">http://submain.com/support/feedback/</a>
</p>
<p>
<strong>
<br>
Note to the GhostDoc Pro v4 users</strong>: The v4.x license codes won't work with
the v5.0. For users with License Protection and active Software Assurance subscription
we have sent out the v5.x license codes. If you have not received or misplaced your
new license, you can retrieve it on the <a href="http://submain.com/MyAccount/" target="_blank">My
Account</a> page. Users without the License Protection or with expired Software Assurance
subscription will need to purchase the new version - currently we are not offering
upgrade path other than the Software Assurance subscription. For information about
the upgrade protection see our <a href="http://support.submain.com/kb/a40/software-assurance-and-support-renewal-reinstatement.aspx" target="_blank">Software
Assurance and Support - Renewal / Reinstatement Terms</a>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=5ad25e66-488e-4a5e-9628-8c92667d7675" />http://submain.com/blog/CommentView,guid,5ad25e66-488e-4a5e-9628-8c92667d7675.aspxGhostDocNewsReleaseshttp://submain.com/blog/Trackback.aspx?guid=f6d7d77d-3853-4379-8d87-dfa245b29ff4http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,f6d7d77d-3853-4379-8d87-dfa245b29ff4.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,f6d7d77d-3853-4379-8d87-dfa245b29ff4.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=f6d7d77d-3853-4379-8d87-dfa245b29ff4

First, we want to thank all of you for the support and loyalty you have given us over
the last few years. We truly have the most amazing and passionate community of developers
on the planet, and it makes our job an absolute joy. If you already have a GhostDoc
Pro with License Protection, rejoice! The upcoming changes are not going to affect
you (and if you were thinking about purchasing additional licenses, now is the time).

If you don't have GhostDoc Pro, this is your last chance to purchase it with the License
Protection and receive free upgrades for the life of the product.

We are working harder than ever to bring more great features to your favorite plugin.
We are super excited about the things we're working on and can't wait to share them
with you over the next few months!

We will be making upgrade protection changes for new GhostDoc Pro users in order to
align GhostDoc Pro maintenance with all other SubMain's products.

Starting January 1, 2015, for new license purchases only we are retiring
the lifetime License Protection option for GhostDoc Pro and replacing it with annual
Software Assurance subscription offering.

If you have been thinking buying new license(s) or adding more licenses, now
is the time! Purchase GhostDoc Pro with License Protection by December
31, 2014 and save big on future GhostDoc Pro upgrades!

SubMain customers can purchase 12 months of Software Assurance subscription with the
purchase of any new license. Upgrade protection includes access to all major and minor
version upgrades for 12 months from the date of purchase at no additional charge.

For example, if a new GhostDoc Pro license is purchased on May 1, 2015, upgrade protection
will expire on April 30, 2016. During this time, the customer can download and install
any minor version upgrades. In addition, if SubMain issues a major release of GhostDoc
Pro during the subscription period, the license can be upgraded to the latest version
at no additional charge. With SubMain's Software Assurance, customers will always
have access to the latest features and fixes.

Again, please note that this new upgrade protection subscription will only
affect new license purchases after January 1, 2015. All existing customer
licenses with License Protection and those purchased by December 31st, 2014 will be
honored and free upgrades will be provided to users with License Protection for the
life of the product.

Thanks again for all of your support. Keep an eye out for more new exciting releases
coming very soon!

[Edit: added some frequently asked questions]

Q: How does the Software Assurance subscription work for GhostDoc Pro?

A: It works the same way it does for all other SubMain products - the initial subscription
term is one year from the purchase date. It is renewed at the end of the subscription
for another year unless you choose to discontinue the subscription. If your license
purchase has not included subscription auto-renewal, you need to renew your subscription
manually in order to keep it current.

Q: I have purchased GhostDoc Pro without the License Protection. Can I add
it now?

A: No, License Protection is not something that can be added after the license purchase.

Q: How long do I get updates if I don't purchase Software Assurance subscription?

A: With a new license purchase you get 90 days of free product updates if you have
not purchased the Software Assurance subscription option.

Q: With License Protection do I get all future features or not?

A: Customers who purchased GhostDoc Pro with License Protection before it
is replaced with the Software Assurance subscription get exactly the same features
as the users with subscription. Think of the soon to be retired License Protection
as a prepaid lifetime subscription.

Upcoming upgrade protection change for new GhostDoc Pro usershttp://submain.com/blog/PermaLink,guid,f6d7d77d-3853-4379-8d87-dfa245b29ff4.aspxhttp://submain.com/blog/UpcomingUpgradeProtectionChangeForNewGhostDocProUsers.aspx
Thu, 04 Dec 2014 19:40:31 GMT<p>
First, we want to thank all of you for the support and loyalty you have given us over
the last few years. We truly have the most amazing and passionate community of developers
on the planet, and it makes our job an absolute joy. If you already have a GhostDoc
Pro with License Protection, rejoice! The upcoming changes are not going to affect
you (and if you were thinking about purchasing additional licenses, now is the time).
</p>
<p>
If you don't have GhostDoc Pro, this is your last chance to purchase it with the License
Protection and receive free upgrades for the life of the product.
</p>
<p>
We are working harder than ever to bring more great features to your favorite plugin.
We are super excited about the things we're working on and can't wait to share them
with you over the next few months!
</p>
<p>
We will be making upgrade protection changes for new GhostDoc Pro users in order to
align GhostDoc Pro maintenance with all other SubMain's products.
</p>
<p>
Starting January 1, 2015, <em>for new license purchases only</em> we are retiring
the lifetime License Protection option for GhostDoc Pro and replacing it with annual
Software Assurance subscription offering.
</p>
<p>
<strong>If you have been thinking buying new license(s) or adding more licenses, now
is the time!</strong> Purchase GhostDoc Pro with License Protection <strong>by December
31, 2014</strong> and save big on future GhostDoc Pro upgrades!
</p>
<blockquote style="font-size: 14px"><a href="http://submain.com/order-ghostdoc.aspx?utm_campaign=ghostdoc&amp;utm_medium=blog&amp;utm_source=license-protection&amp;utm_content=link" target="_blank">Purchase
GhostDoc Pro w/ License Protection now</a></blockquote>
<p>
<strong>What is Software Assurance subscription?</strong>
</p>
<p>
SubMain customers can purchase 12 months of Software Assurance subscription with the
purchase of any new license. Upgrade protection includes access to all major and minor
version upgrades for 12 months from the date of purchase at no additional charge.
</p>
<p>
<a href="http://support.submain.com/kb/a40/software-assurance-and-support-renewal-reinstatement.aspx" target="_blank"><img title="Upgrade Protection Timeline 2015" style="border-top: 0px; border-right: 0px; background-image: none; border-bottom: 0px; float: right; padding-top: 0px; padding-left: 0px; border-left: 0px; display: inline; padding-right: 0px" border="0" alt="Upgrade Protection Timeline 2015" src="http://submain.com/blog/content/binary/Windows-Live-Writer/fe6173250677_9A9F/Upgrade%20Protection%20Timeline%202015_3.png" width="450" align="right" height="139"></a>
</p>
<p>
For example, if a new GhostDoc Pro license is purchased on May 1, 2015, upgrade protection
will expire on April 30, 2016. During this time, the customer can download and install
any minor version upgrades. In addition, if SubMain issues a major release of GhostDoc
Pro during the subscription period, the license can be upgraded to the latest version
at no additional charge. With SubMain's Software Assurance, customers will always
have access to the latest features and fixes.<br>
</p>
<p>
For more information please see <a href="http://support.submain.com/kb/a40/software-assurance-and-support-renewal-reinstatement.aspx" target="_blank">Software
Assurance - Renewal / Reinstatement</a>
</p>
<blockquote>
<p>
Again, please note that this <strong>new upgrade protection subscription will only
affect new license purchases after January 1, 2015</strong>. All existing customer
licenses with License Protection and those purchased by December 31st, 2014 will be
honored and free upgrades will be provided to users with License Protection for the
life of the product.
</p>
</blockquote>
<p>
Thanks again for all of your support. Keep an eye out for more new exciting releases
coming very soon!
</p>
<p>
<em>[Edit: added some frequently asked questions]</em>
</p>
<p>
Q: <strong>How does the Software Assurance subscription work for GhostDoc Pro?</strong>
</p>
<p>
A: It works the same way it does for all other SubMain products - the initial subscription
term is one year from the purchase date. It is renewed at the end of the subscription
for another year unless you choose to discontinue the subscription. If your license
purchase has not included subscription auto-renewal, you need to renew your subscription
manually in order to keep it current.
</p>
<p>
For more information please see <a href="http://support.submain.com/kb/a40/software-assurance-and-support-renewal-reinstatement.aspx" target="_blank">Software
Assurance - Renewal / Reinstatement</a>
</p>
<p>
Q: <strong>I have purchased GhostDoc Pro without the License Protection. Can I add
it now?</strong>
</p>
<p>
A: No, License Protection is not something that can be added after the license purchase.
</p>
<p>
Q: <strong>How long do I get updates if I don't purchase Software Assurance subscription?</strong>
</p>
<p>
A: With a new license purchase you get 90 days of free product updates if you have
not purchased the Software Assurance subscription option.
</p>
<p>
Q: <strong>With License Protection do I get all future features or not?</strong>
</p>
<p>
A: Customers who purchased GhostDoc Pro with License Protection <em>before</em> it
is replaced with the Software Assurance subscription get exactly the same features
as the users with subscription. Think of the soon to be retired License Protection
as a prepaid lifetime subscription.
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=f6d7d77d-3853-4379-8d87-dfa245b29ff4" />http://submain.com/blog/CommentView,guid,f6d7d77d-3853-4379-8d87-dfa245b29ff4.aspxGeneralGhostDocNewshttp://submain.com/blog/Trackback.aspx?guid=72a70921-039e-41a9-a58e-f658fb44f2afhttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,72a70921-039e-41a9-a58e-f658fb44f2af.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,72a70921-039e-41a9-a58e-f658fb44f2af.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=72a70921-039e-41a9-a58e-f658fb44f2af

GhostDoc v4.9 Update 1 adds support for Shared Projects in all editions and introduces
command line version in the Enterprise Edition:

(Ent) New feature - command line version - enables generating help documentation during
build process for a specific Help Configuration

As
an active member of the Microsoft Visual Studio Industry Partner (VSIP) program, we
again are proud to be VS2013 sim-ship partner and shipping all editions of GhostDoc
v4.8 today simultaneously with the release of Visual Studio 2013.

This release includes official and complete support for Visual Studio 2013 as well
as number of improvements and fixes. For details please see What's
New in GhostDoc v4.8

We are happy to introduce the release of GhostDoc
v4.7, a version that is greatly influenced by feedback from our users. It extends
Visual Studio 2013 support and introduces an Enterprise version, Help Configurations,
Help Content Targeting, embedding images into help markup, hyperlinking to base .NET
Framework classes, abbreviation expansion, Non-breaking Words list, and much more:

Visual Studio 2013 support

Introduced GhostDoc Enterprise

(Pro) New Help Configuration feature - save custom configured help generation
settings and switch between them easily

(Pro) Help Content Targeting - ability to create a (partial) 'filtered'
help file based on attributes by using <tags/> in XML Comment and tag filtering
in Help Configuration. If you need to have different help content for public API users,
testers, internal documentation, etc, you can do that now!

We have identified a clear need for a new kind of GhostDoc product, specifically suitable
for enterprises and customers who need advanced configuration features for the help
file output.

The GhostDoc Enterprise version that we are officially introducing today offers silent
deployment options, full customization of the template and layout of the Comment Preview
and Help Files. The Enterprise license customers are also eligible for the on-premises
Enterprise Licensing Server option.

The new Help Configuration feature enables you to create ready-to-use help generation
profiles. You can easily switch between profiles, depending on what kind of help you
are producing. Also you can define attributes with <tags /> in XML Comment and
use tag filtering in Help Configuration to target Help content to your specific audience.

While GhostDoc Pro T4 template mechanism provides maximum flexibility how you can
tweak and reconfigure your XML Comments and even regular comments, until now there
was no easy way to share the set of templates with your team or the community.

Today we are introducing Template Libraries - you can Export the whole set of your
custom templates and distribute it as one file which can be imported. Template Library
includes meta-data - the library author, company name and contact information. To
access the feature use Options -> Rules -> Export.

We will be hosting a section on our web site where we publish GhostDoc Pro Template
Libraries we release. If you have specific comment formats you want us to release, send
your requests in.

We also want to encourage sharing your templates with the community. Contact
us if you have template library you was us to publish.

New Help File Formats and Options

When we introduced a simple single click way of generating help file from your project
XML comments, we realized that just one CHM format is not enough and we would need
to add options to tweak your help file output.

Today GhostDoc Pro can build into the following help file formats:

Html Help1 (.CHM)

MS Help 2 (.HxS)

MS Help Viewer aka MS Help 3 (.MSHC)

Website (HTML, ASP.NET, PHP)

You also have the following options when building help file with GhostDoc Pro:

Select solution projects that you want to be included into the
help file

Define Header and Footer for the help file pages

Decide whether you want to include Private, Internal, Protected
members

Note to Beta testers: We appreciate your contribution to this release
and we will be contacting shortly those of you who provided feedback during the alpha/beta
testing program.

Note to GhostDoc Pro v3 users: We have changed licensing schema in
v4.0 and your v3.x license codes won't work with v4.0. For users with License Protection
we will be sending v4.x license codes shortly. Users without the License Protection
have to purchase new version - currently we are not offering upgrade path other than
the License Protection program.

Note to GhostDoc Pro v3 users: Please use the temporary license above,
your v3 license won’t work with v4. Once v4 is released we will be sending new license
codes to those of you with License Protection.

After a round of private Alpha/Beta for GhostDoc we are excited to release Beta 2
of GhostDoc and GhostDoc Pro and make it available as part of the public Beta program!

Version 4 is a major milestone for us with great new features and rewrites that we
have done over the last year. Here are the most significant additions to the GhostDoc
feature set:

The Pro trial license will allow you to run it for 14 days. To get past that point,
please use the license below:

063A0-29A49-A6083-692D1-32CFC
<- good through 09/01/2012

19E95-459BB-E531B-288C0-08659
<- good through 10/01/2012

Note to GhostDoc Pro v3 users: Please use the temporary license above,
your v3 license won’t work with v4. Once v4 is released we will be sending new license
codes to those of you with License Protection.

We posted
earlier that on 2/29 when Microsoft announced the Visual Studio 11 Beta, SubMain
was one of the first partners with CodeIt.Right product that provided full support
for the new VS Beta. We currently are running private Beta program for our GhostDoc
product that is also VS11 Beta compatible.

We are happy to announce that SubMain is one of the partners to sim-ship (Simultaneously
Ship) our products together with the Visual Studio 11 RTM! You will be able to enjoy
fully compatible version of our products when you install Visual Studio 11 on the
release day!

In the meantime you are welcome to test drive CodeIt.Right and GhostDoc together
with Visual Studio 11 Beta:

CodeIt.Right to sim-ship with Visual Studio 11!http://submain.com/blog/PermaLink,guid,4d0671b5-333b-4428-a9db-dd0ac6c64e54.aspxhttp://submain.com/blog/CodeItRightToSimshipWithVisualStudio11.aspx
Thu, 05 Apr 2012 14:49:00 GMT<p>
We <a href="http://submain.com/blog/CodeItRightV20BetaIsAvailableAsPartOfTheVS11BetaBundle.aspx">posted
earlier</a> that on 2/29 when Microsoft announced the Visual Studio 11 Beta, SubMain
was one of the first partners with CodeIt.Right product that provided full support
for the new VS Beta. We currently are running private Beta program for our GhostDoc
product that is also VS11 Beta compatible.
</p>
<p>
We are happy to announce that SubMain is one of the partners to sim-ship (Simultaneously
Ship) our products together with the Visual Studio 11 RTM! You will be able to enjoy
fully compatible version of our products when you install Visual Studio 11 on the
release day!
</p>
<p>
In the meantime you are welcome to test drive <a href="http://submain.com/codeit.right/">CodeIt.Right</a> and <a href="http://submain.com/ghostdoc/">GhostDoc</a> together
with Visual Studio 11 Beta:
</p>
<p>
</p>
<center><a href="http://go.microsoft.com/?linkid=9801747"><img style="background-image: none; border-bottom: 0px; border-left: 0px; padding-left: 0px; padding-right: 0px; border-top: 0px; border-right: 0px; padding-top: 0px; align: center" title="Get-VS-11-Beta" alt="Get-VS-11-Beta" src="http://submain.com/blog/content/binary/Windows-Live-Writer/4ab7c7f5a900_A5F/Get-VS-11-Beta_3.png" border="0" height="78" width="218"></a>
</center>
<p>
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=4d0671b5-333b-4428-a9db-dd0ac6c64e54" />http://submain.com/blog/CommentView,guid,4d0671b5-333b-4428-a9db-dd0ac6c64e54.aspxCodeIt.RightGhostDochttp://submain.com/blog/Trackback.aspx?guid=6a4d197c-fc6d-4f7f-8dac-ff42190b4b1fhttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,6a4d197c-fc6d-4f7f-8dac-ff42190b4b1f.aspxSerge Baranovskyhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=6a4d197c-fc6d-4f7f-8dac-ff42190b4b1f

PrettyCode.Print and StudioTools no longer fit our strategic corporate direction to
deliver best code quality tools on the market.

Discontinuing these products enables us to reinvest the efforts into our flagship
products and offer even better code quality tools. We will be releasing new greatly
enhanced versions of our existing products as well as new products over the next six
months. For a sneak peek of what’s coming please see our Product
Feedback board.

PrettyCode.Print
PrettyCode.Print for VB6/VBA and PrettyCode.Print for .NET will no longer be further
developed. Both products will be converted into a free download in their
current state. While we will continue to offer technical support for PrettyCode.Print
products for six more month from now, there will be no enhancements, improvements
nor bug fixes for these two products. You can download PrettyCode.Print for VB6/VBA
and PrettyCode.Print for .NET in the Community
Downloads section.

CodeIt.Once
CodeIt.Once is retired and no longer available for download. We encourage you to learn
about our CodeIt.Right product which
offers automated refactorings and proactively finds the opportunities for refactoring
and improving your code.

StudioTools
StudioTools is retired and will no longer be offered for download or supported.

CodeSpell
CodeSpell will not be available for purchase for approximately 6 months. The CodeSpell
engine is being rewritten to allow greater flexibility and better features, after
which, the code spelling feature will be offered as part of our GhostDoc
Pro product. All customers that purchased CodeSpell from SubMain (after March
9th, 2010) will be offered, at no charge, the equivalent number of licenses for GhostDoc
Pro once the code spelling feature is released.

We sincerely appreciate your continued support and look forward to working with you
in the future.

Retiring PrettyCode.Print and StudioTools; CodeSpell to be merged into GhostDoc Prohttp://submain.com/blog/PermaLink,guid,6a4d197c-fc6d-4f7f-8dac-ff42190b4b1f.aspxhttp://submain.com/blog/RetiringPrettyCodePrintAndStudioToolsCodeSpellToBeMergedIntoGhostDocPro.aspx
Thu, 25 Aug 2011 06:47:26 GMT<p>
PrettyCode.Print and StudioTools no longer fit our strategic corporate direction to
deliver best code quality tools on the market.
</p>
<p>
Discontinuing these products enables us to reinvest the efforts into our flagship
products and offer even better code quality tools. We will be releasing new greatly
enhanced versions of our existing products as well as new products over the next six
months. For a sneak peek of what’s coming please see our <a href="http://feedback.submain.com/">Product
Feedback</a> board.
</p>
<p>
<strong>PrettyCode.Print</strong>
<br>
PrettyCode.Print for VB6/VBA and PrettyCode.Print for .NET will no longer be further
developed. Both products will be converted into a <em>free download</em> in their
current state. While we will continue to offer technical support for PrettyCode.Print
products for six more month from now, there will be no enhancements, improvements
nor bug fixes for these two products. You can download PrettyCode.Print for VB6/VBA
and PrettyCode.Print for .NET in the <a href="http://community.submain.com/files/folders/retired/default.aspx">Community
Downloads</a> section.
</p>
<p>
<strong>CodeIt.Once</strong>
<br>
CodeIt.Once is retired and no longer available for download. We encourage you to learn
about our <a href="http://submain.com/codeit.right">CodeIt.Right</a> product which
offers automated refactorings and proactively finds the opportunities for refactoring
and improving your code.
</p>
<p>
<strong>StudioTools</strong>
<br>
StudioTools is retired and will no longer be offered for download or supported.
</p>
<p>
<strong>CodeSpell</strong>
<br>
CodeSpell will not be available for purchase for approximately 6 months. The CodeSpell
engine is being rewritten to allow greater flexibility and better features, after
which, the code spelling feature will be offered as part of our <a href="http://submain.com/ghostdoc/">GhostDoc
Pro</a> product. All customers that purchased CodeSpell from SubMain (after March
9th, 2010) will be offered, at no charge, the equivalent number of licenses for GhostDoc
Pro once the code spelling feature is released.
</p>
<p>
We sincerely appreciate your continued support and look forward to working with you
in the future.
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=6a4d197c-fc6d-4f7f-8dac-ff42190b4b1f" />http://submain.com/blog/CommentView,guid,6a4d197c-fc6d-4f7f-8dac-ff42190b4b1f.aspxCodeIt.OnceCodeSpellGhostDocPrettyCode.PrintStudioToolshttp://submain.com/blog/Trackback.aspx?guid=153cb731-77ef-4b60-8785-2845af60f3a3http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,153cb731-77ef-4b60-8785-2845af60f3a3.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,153cb731-77ef-4b60-8785-2845af60f3a3.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=153cb731-77ef-4b60-8785-2845af60f3a3

SubMain is proud to spread the holiday cheer by offering customers best savings of
the year with free 1 year of Software Assurance and Support, free lifetime License
Protection and great savings on multiple license purchases.

Get Software Assurance and Support absolutely free!

From now until January 7, purchase any new CodeIt.Right licenses and receive
1 year of Software Assurance and Support subscription at no additional cost. Normally
priced at $100 per user ($150 per user for Enterprise Edition), Software Assurance
annual subscription plan is the most cost effective and convenient way to stay current
with the latest versions of our products and get priority support when you need it.

Plus free License Protection!

If you purchase just released GhostDoc Pro,
you will receive free License Protection and secure GhostDoc Pro updates and
new versions at no charge for the product lifetime.

GhostDoc Pro Edition is enhanced version of the product that gives users complete
control over your XML Comment content and layout as well as automates XML Comment
generation via batch actions.

Get it today! No hurdles! No hoops!

It is easy to get your free software assurance subscription and license protection.
Just place your order on the SubMain website by
January 7, and we will automatically give you the free year of software assurance
and support subscription. If your purchase includes GhostDoc, you will automatically
receive lifetime license protection for free too. No hassle. No headaches.

But wait, there is more!

On the top of the free offers above, you can save even more when you buy multiple
CodeIt.Right licenses:

Holiday Offer: Complimentary Software Assurance and Licence Protection + Save up to 30%!http://submain.com/blog/PermaLink,guid,153cb731-77ef-4b60-8785-2845af60f3a3.aspxhttp://submain.com/blog/HolidayOfferComplimentarySoftwareAssuranceAndLicenceProtectionSaveUpTo30.aspx
Fri, 10 Dec 2010 09:15:02 GMT<img style="border: 0px none; display: inline; margin-left: 10px; margin-right: 0px;" title="Holiday Offer" alt="Holiday Offer" src="http://submain.com/promotions/201012/images/offer2.png" align="right" border="0">
<p>
SubMain is proud to spread the holiday cheer by offering customers best savings of
the year with free 1 year of Software Assurance and Support, free lifetime License
Protection and great savings on multiple license purchases.
</p>
<p>
<b><span style="font-size: 16px;">Get Software Assurance and Support absolutely free!</span></b>
</p>
<p>
From now until January 7, purchase any <b>new CodeIt.Right licenses</b> and <b>receive
1 year of Software Assurance and Support subscription at no additional cost</b>. Normally
priced at $100 per user ($150 per user for Enterprise Edition), Software Assurance
annual subscription plan is the most cost effective and convenient way to stay current
with the latest versions of our products and get priority support when you need it.
</p>
<p>
<b><span style="font-size: 16px;">Plus free License Protection!</span></b>
</p>
<p>
If you purchase just released <b><a href="http://submain.com/ghostdoc/">GhostDoc Pro</a></b>,
you will receive <b>free License Protection</b> and secure GhostDoc Pro updates and
new versions at no charge for the product lifetime.
</p>
<p>
GhostDoc Pro Edition is enhanced version of the product that gives users complete
control over your XML Comment content and layout as well as automates XML Comment
generation via batch actions.<br>
</p>
<b><span style="font-size: 16px;">Get it today! No hurdles! No hoops!</span></b>
<p>
It is easy to get your free software assurance subscription and license protection.
Just place your order on the <a href="http://submain.com/order">SubMain website</a> by
January 7, and we will automatically give you the free year of software assurance
and support subscription. If your purchase includes GhostDoc, you will automatically
receive lifetime license protection for free too. No hassle. No headaches.<br>
</p>
<p>
<b><span style="font-size: 16px;">But wait, there is more!</span></b>
</p>
<p>
On the top of the free offers above, you can save even more when you buy multiple
CodeIt.Right licenses:
</p>
<ul>
<li>
<b>Save 20%</b> on <b>CodeIt.Right Standard</b> Edition 5 license pack<br>
<br>
</li>
<li>
<b>Save 30%</b> on <b>CodeIt.Right Enterprise</b> Edition 10 license pack<br>
</li>
</ul>
<p>
Email us at <a href="mailto:sales@submain.com?subject=Holiday%20Offer%20CodeIt.Right%205/10%20pack%20discount%20inquiry">sales@submain.com</a> for
information on the the 5 and 10 pack discounts.<br>
</p>
<b><span style="font-size: 16px;"></span></b>
<p>
<span style="font-size: 16px;">Need more info about SubMain products?</span>
</p>
<blockquote><a href="http://submain.com/products"><img src="http://submain.com/images/button_LearnMore.gif" alt="Learn more about SubMain products" title="Learn more about SubMain products" border="0"></a></blockquote>
<p>
<span style="font-size: 16px;">Ready to get your holiday bonus?</span>
</p>
<blockquote><a href="http://submain.com/order"><img src="http://submain.com/images/button_BuyNow.gif" alt="Buy now for the holiday offer" title="Buy now for the holiday offer" border="0"></a></blockquote>
<p>
<b><span style="font-size: 16px;">Still have questions?</span></b>
</p>
<p>
No problem! Contact the SubMain sales department via email <a href="mailto:sales@submain.com?subject=Holiday%20Offer%20inquiry">sales@submain.com</a>
</p>
<p>
&nbsp;
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=153cb731-77ef-4b60-8785-2845af60f3a3" />http://submain.com/blog/CommentView,guid,153cb731-77ef-4b60-8785-2845af60f3a3.aspxCodeIt.RightGhostDocPromotionshttp://submain.com/blog/Trackback.aspx?guid=5af69534-7724-46c6-9d58-58606a1f2d69http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,5af69534-7724-46c6-9d58-58606a1f2d69.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,5af69534-7724-46c6-9d58-58606a1f2d69.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=5af69534-7724-46c6-9d58-58606a1f2d69

Today we are announcing the release of GhostDoc v3.0 - a new major release of the
product. This version includes product usability and menu changes, adds many new features
- menus, configuration rules, configuration options. It also features new error logging
to improve troubleshooting of GhostDoc issues. The new version introduces GhostDoc
Pro Edition - enhanced version of the product that gives users complete control
over your XML Comment content and layout as well as automates XML Comment generation
via batch actions.

Please note GhostDoc EULA was
updated to reflect the introduction of GhostDoc Pro.

Released: GhostDoc and GhostDoc Pro v3.0.10340http://submain.com/blog/PermaLink,guid,5af69534-7724-46c6-9d58-58606a1f2d69.aspxhttp://submain.com/blog/ReleasedGhostDocAndGhostDocProV3010340.aspx
Thu, 09 Dec 2010 20:55:34 GMT<p>
Today we are announcing the release of GhostDoc v3.0 - a new major release of the
product. This version includes product usability and menu changes, adds many new features
- menus, configuration rules, configuration options. It also features new error logging
to improve troubleshooting of GhostDoc issues. The new version introduces <a href="http://submain.com/ghostdoc/"><b>GhostDoc
Pro</b></a> Edition - enhanced version of the product that gives users complete control
over your XML Comment content and layout as well as automates XML Comment generation
via batch actions.
</p>
<p>
For Edition comparison please see GhostDoc product page - <a href="http://submain.com/ghostdoc/">http://submain.com/ghostdoc/</a>
</p>
<a href="http://submain.com/ghostdoc/"><img style="border-bottom: 0px; border-left: 0px; display: inline; margin-left: 10px; border-top: 0px; margin-right: 0px; border-right: 0px" title="GhostDoc Pro" border="0" alt="GhostDoc Pro" align="right" src="http://submain.com/images/ghostdoc_pro_logo_106x27.png"></a>
<p>
New in v3.0:<br>
</p>
<ul>
<li>
(<i>Pro Only</i>) New <b>Document Type</b> feature - generates XML comments for the
entire type/class
<li>
(<i>Pro Only</i>) New <b>Document File</b> feature - generates XML comments for the
entire file
<li>
(<i>Pro Only</i>) Introduced T4 template based rules that replace rule macros of the
Free version
<li>
Improved support for VS2010
<li>
New Load/Unload menu items allow to disable GhostDoc temporary without uninstalling
it<br>
<li>
New Help menu item<br>
<li>
New option to and menu to Re-assign Shortcut
<li>
Added Rule for read-only property to turn off generation of the tag line
<li>
Added Rule for private constructor
<li>
Added support for new tags - &lt;inheritdoc&gt;, &lt;author&gt; and &lt;remarks&gt;
<li>
Added support for enums, delegates and fields
<li>
Added option to modify Configuration Folder path
<li>
Added option to Keep Single Line when for long comments<br>
<li>
Changed leading tabs to leading spaces for compatibility with other products<br>
<li>
Changed "gets or sets" summary prefix to just "Gets" when setter is private
<li>
Fixed automatically implemented properties issue
</li>
</ul>
<p>
GhostDoc and GhostDoc Pro build 3.0.10340 are available for download right now at <a href="http://submain.com/download/ghostdoc/">http://submain.com/download/ghostdoc/</a>
</p>
<p>
Please note <a href="http://submain.com/ghostdoc/EULA.aspx">GhostDoc EULA</a> was
updated to reflect the introduction of GhostDoc Pro.
</p>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=5af69534-7724-46c6-9d58-58606a1f2d69" />http://submain.com/blog/CommentView,guid,5af69534-7724-46c6-9d58-58606a1f2d69.aspxGhostDocReleaseshttp://submain.com/blog/Trackback.aspx?guid=27e7bd93-ede8-4430-a5a4-1293664a6a5bhttp://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,27e7bd93-ede8-4430-a5a4-1293664a6a5b.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,27e7bd93-ede8-4430-a5a4-1293664a6a5b.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=27e7bd93-ede8-4430-a5a4-1293664a6a5b

Code Quality developer tools is the direction we've been following since the introduction
of CodeIt.Right and we are taking this commitment to the next level in 2010 with two
new products and new features for our existing products. One of the new products
to be released in 2010 will assist in unit testing, code coverage and test code profiling;
the second new product will be complementary to CodeIt.Right. All three products
together will comprise our new Code Quality Suite. Additionally, we will continue
to keep up with the Visual Studio 2010 release schedule and have all of our products
2010 compatible when VS2010 is RTM.

Here is what we are planning for 2010:

New product!

Coming March 2010: we are adding to our product line by offering a unit test
runner and code coverage product.

New product!

Project Anelare (code name) - we will provide details on this project as we
get closer to a public preview. At this point we can share that this will be
product complementary to CodeIt.Right - together they will encompass our code quality
package.

VS2010 support

For all products - most of our products are compatible with VS2010 RC, and
we will be VS2010 RTM compatible by the time it RTMs.

CodeIt.Right

Optimized rule library performance: the new version will be released
the first week in March!

Community Rule Valuation & Review: we are pioneering "social" in code analysis
by enabling the community to rate rules and provide feedback; as well as leverage
the community feedback, best uses and best practices for each rule.

We are currently prioritizing the feature set for the new version of GhostDoc. If
you have a feature request that you have not submitted yet, share them with us in
the GhostDoc
forum.

Stay tuned to our blog for more details about our progress!

2010 Product Roadmaphttp://submain.com/blog/PermaLink,guid,27e7bd93-ede8-4430-a5a4-1293664a6a5b.aspxhttp://submain.com/blog/2010ProductRoadmap.aspx
Tue, 23 Feb 2010 17:13:00 GMT<img style="border: 0px none ; display: inline; margin-left: 10px; margin-right: 0px;" title="Roadmap_426x282" alt="Roadmap_426x282" src="http://submain.com/blog/content/binary/WindowsLiveWriter/d77c81193a72_14EED/Roadmap_426x282_3.jpg" height="203" align="right" border="0" width="304">
<p>
Code Quality developer tools is the direction we've been following since the introduction
of CodeIt.Right and we are taking this commitment to the next level in 2010 with two
new products and new features for our existing products.&nbsp; One of the new products
to be released in 2010 will assist in unit testing, code coverage and test code profiling;
the second new product will be complementary to CodeIt.Right.&nbsp; All three products
together will comprise our new Code Quality Suite.&nbsp; Additionally, we will continue
to keep up with the Visual Studio 2010 release schedule and have all of our products
2010 compatible when VS2010 is RTM.
</p>
<p>
Here is what we are planning for 2010:
</p>
<ul>
<li>
<strong>New product</strong><b>!</b>
<br>
<br>
</li>
<ul>
<li>
Coming March 2010:&nbsp; we are adding to our product line by offering a unit test
runner and code coverage product.<br>
<br>
</li>
</ul>
<li>
<strong>New product!</strong>
<br>
<br>
</li>
<ul>
<li>
<i>Project Anelare</i> (code name) - we will provide details on this project as we
get closer to a public preview.&nbsp; At this point we can share that this will be
product complementary to CodeIt.Right - together they will encompass our code quality
package.<br>
<br>
</li>
</ul>
<li>
<strong>VS2010 support</strong>
<br>
<br>
</li>
<ul>
<li>
<i>For all products</i> - most of our products are compatible with VS2010 RC, and
we will be VS2010 RTM compatible by the time it RTMs.
<br>
<br>
</li>
</ul>
<li>
<strong>CodeIt.Right<br>
<br>
</strong>
</li>
<ul>
<li>
<u>Optimized rule library performance</u>:&nbsp; the new version will be released
the <b>first week in March</b>!<br>
<br>
</li>
<li>
<u>Community Rule Valuation &amp; Review</u>: we are pioneering "social" in code analysis
by enabling the community to rate rules and provide feedback; as well as leverage
the community feedback, best uses and best practices for each rule.<br>
<br>
</li>
<li>
<u>NEW Rules</u> - with emphasis on security, FxCop/StyleCop parity, SharePoint, WPF
&amp; Silverlight rules.<br>
<br>
</li>
<li>
(EE) <u>Trend Analysis</u>: monitor code quality improvements over time.<br>
<br>
</li>
<li>
(EE) <u>Integration with manual code review tools</u>.<br>
<br>
</li>
<li>
<u>Global Suppressions</u>:&nbsp; adding support for GlobalSuppressions and extending
syntax of the SuppressMessage attribute for more flexible in-code exclusions.<br>
<br>
</li>
<li>
<u>Multi-select in the violations list</u>.<br>
<br>
</li>
<li>
<u>Copy Rule feature</u>:&nbsp; clone and change rule instance configuration<br>
<br>
</li>
<li>
<u>Command line enhancements</u>: open command line/build violations output in Visual
Studio for correction<br>
<br>
</li>
<li>
<u>Annotation</u>: for excludes and corrections<br>
<br>
</li>
<li>
<u>XAML support</u>:&nbsp; enables building Silverlight and WPF specific rules<br>
<br>
</li>
<li>
<u>Profile Wizard</u>:&nbsp; quick start no-brainer user/project profile based on
the project type, importance, community valuation, favorite food, etc<br>
<br>
</li>
</ul>
<li>
<strong>GhostDoc</strong>
<br>
<br>
</li>
<ul>
<li>
We are currently prioritizing the feature set for the new version of GhostDoc. If
you have a feature request that you have not submitted yet, share them with us in
the <a href="http://community.submain.com/forums/30/ShowForum.aspx" target="_blank">GhostDoc
forum</a>.<br>
<br>
</li>
</ul>
</ul>
Stay tuned to our blog for more details about our progress!<br>
<br>
<img width="0" height="0" src="http://submain.com/blog/aggbug.ashx?id=27e7bd93-ede8-4430-a5a4-1293664a6a5b" />http://submain.com/blog/CommentView,guid,27e7bd93-ede8-4430-a5a4-1293664a6a5b.aspxCodeIt.RightGhostDocRuleshttp://submain.com/blog/Trackback.aspx?guid=12958242-de8e-4890-935d-b00f454fe8a9http://submain.com/blog/pingback.aspxhttp://submain.com/blog/PermaLink,guid,12958242-de8e-4890-935d-b00f454fe8a9.aspxSerge Baranovskyhttp://submain.com/blog/CommentView,guid,12958242-de8e-4890-935d-b00f454fe8a9.aspxhttp://submain.com/blog/SyndicationService.asmx/GetEntryCommentsRss?guid=12958242-de8e-4890-935d-b00f454fe8a9

As announced
earlier today we just closed the acquisition of the popular XML Comment helper
tool GhostDoc. We, SubMain, will continue to evolve the tool and distribute it as
a free product.

We are also announcing today the availability of the new version of GhostDoc v2.5.09150
which improves the user setup experience, adds support for Visual Studio 2010 Beta
1 and full support for Visual Basic.

Additionally, today we are making available a new version of CodeIt.Right (v1.6.09151)
that adds the IntelliComment feature based on the GhostDoc algorithm and offers improved
and automated generation of XML Comments.

We are very excited about taking over the future of an excellent tool such as GhostDoc!
We are committed to maintaining this wonderful free tool and we welcome the community feedback
and suggestions.