Fighting against GhostDoc abusing
GhostDoc by SubMain is great tool for documenting source code. It is able to generate documentation from methods and properties names. It analyzes names and then offers appropriate description. GhostDoc is also able to use description of interface member that current property or method implements. And it takes only one simple key press.
Well, GhostDoc is great tool and I think it makes developers life easier. But not always. Don’t blame GhostDoc – the real problem is (like always) between chair and keyboard!
How to abuse GhostDoc
GhostDoc is like every good invention – one can use it and abuse it. Like a gun – you can use it to protect yourself or your home or country and you can use it to kill someone just for fun. Here is one real-life scenario.
One of the most painful things one developer can do is documenting code using GhostDoc automatically generated code with out worrying if documentation helps other developers or not. Image the class that is full of auto-generated documentation like this.
/// <summary>
/// Sets the employee phone.
/// </summary>
/// <param name="value">The value.</param>
public void SetEmployeePhone(string value)
{
phoneLabel.Text = value;
}
Looking at method name I get exactly the same information that documentation sais - this method sets employee phone somewhere. But what is the phone here? Is it phone number or phone model or phone type? We know only that there is phone and we know that it has value. But where this value goes? Who knows…
How bad documentation affects development?
For this short method I was able to ask three questions. Let’s suppose we have 20 methods documented like this – it makes 60 questions. This amount of questions refers to serious problem of understandability of documentation. Doesn’t matter what is written in documentation – are there notes like above or some spicy yellow news about stars – it is worthless and useless for other developers.
Developers who actively abuse GhostDoc are real pain in the ass for those developers who respect their co-workers and want to write quality software. Faulty or crappy code documentation is not only useless but also dangerous because it slows down debugging process – if developer notices that there is documentation available then he or she starts reading it. Every such crappy documentation stops the reader and asks for attention.
How to avoid bad documentation?
There is no good way unless one writes brilliant GREP or PowerShell scripts to detect weird documentation blocks by patterns. Besides automatic discovery of crappy documentation you can also use most expensive resource – man power. To fight against literal anarchy in code documentation I am considering the following process:
- Establish rules for code documentation.
- Make these rules available to all developers.
- Look also at code documentation during code reviews.
- Allow developers to remove crappy documentation as soon as they find one.
- Make compiler generate warnings or errors when documentation is missing.
If you have suggestions then please feel free to drop a comment here.