How to force team members to comment using eclipse plugin or something else

Question

Currently, I am working in a new project and it was difficult for me to understand since there is no comment. I wonder if it is possible to force team members(including me) to add more comments. I would like to automate this ject in jenkins later if possible.

Answer 1

You can run static code checks and their corresponding eclipse plug-ins to enforce comments being made in code.

For e.g. in CheckStyle javadoc can be enforced http://checkstyle.sourceforge.net/config_javadoc.html

Also checkstyle can be easily integrated with Jenkins.

You can also use eclipse java compiler settings for javadoc check.

Go to preferences->java->compiler->javadoc to enforce errors and warnings. Compiler errors and warnings can be easily reported through continuous build

cheers,

Saurav

Answer 2

This needs to be implemented at the source control level, not the IDE level.

If you're using git, you can look into git hooks http://git-scm.com/docs/githooks

This will let you write little scripts that will be run when you commit code. You can write a script to check if the commit includes a valid comment. You can also perhaps allow skipping of comments with a "-force" option or something like that.

Answer 3

I can only recommend to be very, very careful with that. Of course, you may use tools like SONAR, Eclipse Settings and the like to enforce comments.

Buuuuuuuut:

1. You can easily generate comments (/w Eclipse) and -as you probably know- generated comment is not use/helpful at all.
2. In case you add a useful comment and it relies too much on the actual implementation, you also have to maintain it. Whenever the code changes you need to validate if the comment does too. This is often overlooked and creates more confusion then by not having any comment at all. Even though you had a good intention in the first place.
3. "The Truth Lies In The Code"(tm): You can achieve good to understand and easy maintainable code by working very hard on it. This might help to avoid to need any comment at all. Its not easy (and not always possible), I admit that.
4. At least "public API" must be documented. That could be a rule of thumb and it seems managable in a large code base.

I would rather spend more time in having good understandable code instead of "forced comments". You may achieve the complete opposite by enforcing it.

Using Sonar/Eclipse Settings to enforce documentation of public API makes sense to me though.