More checks

Topics: Developer Forum
Jan 21, 2007 at 12:19 PM
Hello all

I'd like to see what your opinion is regarding the following checks:

- the summary element must be present and not empty
- if a method throws an Exception it should be documented
- all method parameters should be documented

I think the first one (summary not empty) is safe to put in as default on (even mandatory) and the other two default off.
Jan 21, 2007 at 1:14 PM
Don't modify the defaults - this translates to: all new features are off by default.

Checking for a non-empty summary and "Were all the parameters documented?" is a really good addition.

Regarding the other option "if a method throws an Exception it should be documented" - how would we (as the policy) know if and which exceptions might be thrown by a method? We cannot possibly check this.

Btw, when talk about such features: how about discussing the possibility to have an extensibility model for checking, kind of a CCCP checking provider that can be plugged in? So people don't need to modify the CCCP, but can "plug in" their additional code comment checks?

Chris
Jan 21, 2007 at 2:08 PM
Regarding thrown exceptions.
If a method contains something like "throw new Exception(...)" I think it's safe to assume that the exception will bubble up the call stack and not be caught inside it (because using exceptions to control execution flow is a bad practice). It may not cover all cases (like exceptions thrown by other methods called from the current one) but I still think it would be pretty useful.
Jan 21, 2007 at 3:59 PM
http://www.sauria.com/blog/computers/programming/java/492.html

I am really not a huge fan of doing such a kind of magic using code comments. My take: this better be a runtime feature, because you know the old adage: "When comment and code disagree, probably both are wrong". No, this won't make it into the main distribution, but we can use it as a plugin sample.

Chris
Jan 21, 2007 at 8:15 PM
I fully agree with Anders Hjelsberg on that one, but I don't think the issues apply here. The only exceptions that should be documented are those thrown directly in the method's body. If you modify the method body and add a new throw statement you must then also update the comments. While I hate java checked exceptions I find this perfectly reasonable :).

If a plugin system is to be developed than I really have no problem with this being a separate plugin, as long as it works :D

Jan 22, 2007 at 7:10 AM
Ok, so let's plan to make this one part of the "Extended Checking Rules Plugin" project, which will verify our plugin system (to be built and designed).

The other two can go to the main branch.

Chris
Apr 29, 2010 at 11:28 AM

Hello,

sorry to revive a thread so old, but that I want to ask is related to this issue.

The plugin system is very good, and I developed some plug-in, such as one that, if a method returns a value then it should be documented with the returns tag.

However, I want to develop a plugin to check if exceptions are thrown from the method body. (As CISCBrain said before, looking for something like "throw new Exception(...)")

The main problem is that I don't know how to access to the source code of the method from the plugin I'm developing ...

Any help / guidance would be welcome.

Thank you very much!