Click here to Skip to main content
15,888,733 members
Please Sign up or sign in to vote.
1.00/5 (1 vote)
See more:
Hi guys!

I need some help in a my challenge!

i have a team (about 6 guys) but they don't have the culture of documenting the code.
To solve it, i'm looking for any tool or add-in to do this (throwing exceptions on build when the code element is not documented)

I've checked some tools:

1- CodeIt.Right (expensive for my employer)
2- CodeRush (does not meet my expectation)
3- StyleCop (only for C#, we use vb.net)
3- FxCop (does not meet my expectation, it is only for assemblies)

Etc...

Someone know's any tool or add-in (preferably free) only to force the code documentation!?!

Thanks a lot
Posted

No automatic processing can replace human culture.

Think of this: if you add comments to existing code, the situation is simple: if this is done automatically, this comment is trivial and hence useless. I actually can see only one exclusion: I find it convenient if all end-of-block places ("end", "}") are commented to match the beginning, and even this is questionable. I find it extremely irritating when I see a standard comment block before every type and method. This is a typical example:
C#
/// <summary>
/// InitializeUi method Initializes UI
/// </summary>
/// <param name="scenarioGenerator">ScenarioGenerator parameter</param>
/// <param name="logicEngine">LogicEngine parameter</param>
/// <param name="scenarioGenerator">ScenarioGenerator parameter</param>
/// <param name="skinManager">SkinManager parameter</param>
void InitializeUi(
    ScenarioGenerator scenarioGenerator,
    LogicEngine logicEngine,
    ScenarioGenerator scenarioGenerator,
    SkinManager skinManager) {
    //...
}


It only pollutes the code and irritates the reader, nothing else. It tells you what you already know. The generation of this comment itself can be useful, but only if the developer adds some useful information to it, that it can go, for example, to XML documentation. But even this should be done very rarely, to select public entities.

At the same time, some minimalistic comments of the auto-generated code is useful, but you are talking about developers' culture, so this is not your concern, as I understand.

This should give you the idea that automatic commenting is evil. It still can be useful, but only if it is mediated through proper development culture. Remember old saying: code should be self-commenting. Indeed, some rare comments should be added, by a hand of a master of comments. So, if the idea to "enforce" commenting came to your mind, how about thinking at this: do you have this culture yourself?

I can tell you what can happen without such culture. The developers will simply ignore the automatic commenting. This commenting will either not appear at all, or, much worse, will be there, purely automatic, untouched by a developer's hand. And of course you won't be able to "enforce" anything.

—SA
 
Share this answer
 
v6
Comments
Estevão C Souza 2-Feb-15 12:36pm    
Hi Sergey,

i'm not trying to create 'automatic comments', i'm looking for a tool that forces the user comment the method or property.
Ex. showing warnings like code analysis of Microsoft or the StyleCop.
'The property 'Name' does not have any comment. Please comment the element'

This is my idea.

I agree to you about the 'machine comments' its only make the code dirty and irritates

Sorry if I did not explain myself properly
Sergey Alexandrovich Kryukov 2-Feb-15 12:58pm    
Sorry, this is a bad idea. It is covered by my answer, if you just think about it.

Say, the project build won't pass if there is no comments. But it will make things much worse: the developer will add comments. Do you understand that most properties should never be commented? And now, imagine the quality of comment written for the sole purpose to shut up the validation. Mind you, this is what you are going to end up with. You can do only one thing: raise the culture of code development in the team.

By the way, I rarely see poorer style recommendation than StyleCop. For example, it tries to "enforce", say, "using" declarations in alphabetic order. What could be worse? This is recommendation for pre-computer era. Because there is no a problem of finding the declaration: the editor has regular expression search. At the same type, using declarations could be grouped by semantic topics. And, even better, good files should be smaller and have very few "using". Again, it's a matter of culture.

And so on. There is so many good-indented stupidity...

And FxCop is quite useful, but if you customize some rules (some are even stupid).

I hope I explained the point.

—SA
Estevão C Souza 2-Feb-15 13:44pm    
I will try to use FxCop and 'put the concepts in their brains'

Tyvm
Sergey Alexandrovich Kryukov 2-Feb-15 13:50pm    
Good idea.

Not that I recommended you FxCop, but I would recommend it if you use it in a certain practical ways, to improve code quality. For example, if will find many trivial performance leaks, such as using an instance method not using "this" (which should be safely eliminated by using "static"), and a lot more. Enforcing naming convention is good, but application-specific names often have to be put in customized project configuration. And a lot more useful stuff, but not all of it. Customization (first of all, exclusion of whole validations or separate rules) is the key here.

—SA
Dave Kreskowiak 2-Feb-15 13:14pm    
There is no such thing.

Also, the appropriate enforcer of such practices is management, no a tool. Team Leads need to do just that - lead. They are the enforcers of coding standards.
We've used GhostDoc[^] to semi-automate production of documentation.

The response by Daniel to this post[^] lists some others I've heard of (I've used Doxygen as well but not the others)

However I would suggest introducing Code Review - otherwise you'll get meaningless comments inserted just to keep the "tool" quiet.

I find a cricket bat helps too.
 
Share this answer
 

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)



CodeProject, 20 Bay Street, 11th Floor Toronto, Ontario, Canada M5J 2N8 +1 (416) 849-8900