Comment Rules

Dear all.

Thank you very much for your help. Thank to Xavier, I have been working in comment rules using the 4.2.x branch and the idea of using line numbers.

I have written a simple rule to detect if a method has or has not a comment. The code is at the end of this post.

The main advantage of this approach is that it is not needed to change the code of PMD.

But there are a couple of drawbacks. You have to consume the comments, so, you need a static or persistent data structure to know the remaining comments (in my example I use a HashMap the static class “StaticIntegers” to store the index of the list of comments).
But the main problem is that you have to consume all the comments. Lets see an example:

/ A */
int a;
void m() { //… }
/ N */
void n() { //… }

If you use the rule for methods only, you will get the comment of the attribute (/* A /) as the comment of the first method ( m() ) because there is not a rule for attributes that consume that comment.

So, by now, I think this is not a good solution.

Feedback is welcome. ¿Can anybody suggest how to improve this idea or another different way?

It would be exciting if we can have something working on 4.2.X using ASTCompilationUnit and without modify the grammar.

Sorry for my bad English.

public class MethodWithoutComment extends AbstractRule {
@Override
public Object visit(ASTMethodDeclaration node, Object data) {
int methodBeginLine;
List<Comment> comments;
Comment lastC, comm = null;
int counter = StaticIntegers.Get("c");

    methodBeginLine = node.getBeginLine();

    ASTCompilationUnit cu = (ASTCompilationUnit) node.getFirstParentOfType(ASTCompilationUnit.class);
    comments = cu.getComments();

    int c;
    for (c = counter; c < comments.size(); c++) {
        lastC = comments.get(c);
        if (lastC.getBeginLine() > methodBeginLine) {
            break;
        }
        comm = lastC;
    }

    StaticIntegers.Put("c", c);

    if (comm != null) {
        System.out.println("Method: " + node.getMethodName() 
                + " Last comment: " + comm.getImage());
    } else {
        System.out.println("No comments for: " + node.getImage());
    }
   return data;
}

Hi Mike,

Have you looked into Checkstyle http://checkstyle.sourceforge.net/ ?

PMD is designed to look at the code structure itself, not it's formatting/appearance. The parsers PMD uses to create the ASTs does not generally make the comments/whitespace available in the AST structure itself. There are places where we check to see for the existence of a comment in a Block, or whether a given Class appears to be used in a JavaDoc comment, and annotate an AST node with that extra information. But the actual comment itself, is not available. This is by intent, as comments would vastly complicate navigation of the AST, as they can appear nearly anywhere and we nearly always do not care about them (i.e. they are ignored just like whitespace).

Thinking out loud here...

I have considered allowing the whitespace and comment blocks to be made available in an alternate version of the AST. A Rule would have to explicitly request this AST, and deal with the corresponding complexities. Taking that a step further to perhaps limit the complexities, would be to add the ability to jump between corresponding nodes in the commented and uncommented ASTs. This could be exposed as a function in XPath. One would use the uncommented AST to identify the basic construct needing analysis, and then switch to the commented AST to dig around.

Anyway, there's a bunch of heavy lifting required to make something like that work. It's not likely I'll get around to something like that soon, if ever. Patches are always welcome.

Good luck,
Ryan

Hi all.

We have been exploring how to write rules for comment blocks. We have followed a different path.

We found that PMD 4.2.2 has a little support for comments. It stores all coments in a list and add them to the only ASTCompilationUnit node.

We used that code to add comment support to ASTClassOrInterfaceDeclaration, ASTFieldDeclaration, ASTMethodDeclarator and ASTConstructorDeclaration. So, now we can write rules like “Non-private method without comment” or “All method that return a value must have a @return tag”.

Although it is easy and fast changing the grammar and the code, this path is a bad design. We repeat code, we destroy the support for tags in UnusedImports and, if there is a new version, we have to change the grammar and the code again. There is also a problem when comment blocks are in unexpected places

Thus, we hope there will be support for comments and comments rules in next major version.

Sorry for my English.