JStyle has support for two built-in scripting languages through which the functionality of the product can be enhanced. These languages are JMScript, a proprietary language built on top of Java and VBScript, Microsoft’s scripting language that is standard on the Windows platforms. A script written in either of these languages has access to the full parsed information of the project being analyzed. In this chapter we will understand why someone would want to write a new comment rule and then learn how to do it. Chapter 6 teaches you how to write independent script executables that are different from comment rules. 

Why Define New Comment Rules? 

JStyle has over 100 built-in comment rules, which it applies when reviewing a set of Java source files. Some of these are related to simple naming and coding conventions, whereas the rest pertain to potential problems in design, reuse, or efficiency. A client who uses JStyle can decide what rules are to be included/excluded in a project by setting appropriate options.  

It is likely that a client follows coding conventions that are not directly supported by JStyle. For example, let us consider a convention No constructor or method should take more than 5 parameters. Although this is not a universally accepted convention, a client may be perfectly justified in following it. Obviously, if you follow this convention, you would like JStyle to report any nonconformities when it reviews a project. Since JStyle does not already know of this rule, you need to define the rule and plug it in. There could be several such examples of comment rules that a client would want to add to JStyle. 

How to Define a New Rule? 

There are a couple of ways to add a new comment rule in JStyle. One that is available to Man Machine Systems (and not to its clients) is to write the rule in C++. This is the most efficient way of defining new comments. However, it might appear somewhat paradoxical to ask a Java developer to write C++ rules! To make it easier to write comments we support two scripting languages – JMScript and VBScript. These languages are interpreted so there is no need to compile your script before installing it. Using either JMScript or VBScript is equally straightforward, so we will show how to implement the above comment in JMScript. 

Writing your own rule requires familiarity with the various project objects. Description of each object is provided in the online help, so will not be repeated here. The easiest way to write a new comment is to use the Comment Wizard, which generates the correct template for your specific need. To launch the wizard, select Tools->Comment Wizard menu. This will pop up a dialog as shown in the following figure. 
 

The dialog has default values supplied by JStyle. For example, the comment ID, severity, file name, and script location are shown. You may change any of the values. Severity is a number in the range 1 to 7, both inclusive. Severity 1 is minor whereas severity 7 depicts a serious violation. Choose a number for your comment based on your view of how serious it is. 

Since our comment applies to constructors and methods of a class, let us select the classification as class member specific comments. The following figure shows our choice of values for this dialog. 
 

We have supplied a severity of 7, but that is not important for us. After entering the values, click the Next button. 

The next dialog lists various program/project elements. We need to select those entities that are relevant to our comment. Our comment applies to methods and constructors of a class, so we select those two. The dialog after our selection appears as follows: 
 

Click the Finish button. JStyle generates a template script at this point and displays it in the editor. 

  
Fig. 7.4

    HandleMethod(Method) {  

        //handle Method (ATXMethod) here 
        //handle Constructor (ATXMethod) here  
        if(Method.Parameters.Count > 5) 
                report(Method.FileName, Method.Line); 
    } 

    class A { 
        A(int i, int j, int k, int l, int m, int n) { } 
        A(int i, int j, int k, int l, int m) { } 
        void f() {} 
        void g(int a) {} 
        void h(int i, int j, int k, int l, int m){} 
        void z(int i, int j, int k, int l, int m, int n) { } 
    } 

Depending on the element category for which you have registered, the framework subsequently calls a handler method (actually a call-back function) in the rule. In our example, the method is HandleMethod(). When this method is invoked by the framework, it passes an argument that represents the current method object. Let us look up the online help at this point. You will notice that ATXMethod is defined under Core Objects. This is the type of the object passed as argument to HandleMethod() (since JMScript is dynamically typed, the type declaration cannot be given). 

Navigating the help further, we find that ATXMethod has a property called Parameters that returns a collection of parameter specifications. Every collection has a Count property using which we can determine the number of elements in that collection. This is what we have used to determine the number of arguments passed to the method or constructor. 
 

Fig. 7.5

Inside the HandleMethod() we call the report() method to signal a violation. This method takes two arguments, the filename and line number of the offending context. The framework collects all such violations and reports them after analysis is complete. 

After you define the script file, to quickly check if your logic is correct, select Test Script on the context sensitive menu in the script window. This will cause the framework to run your script immediately, instead of in the normal cycle. If your script reports any violations, these will be written to the script tab. If you did not create the script through the wizard (perhaps you got the script file from someone else), to add it to the current framework, select Add to Comment Factory from the context sensitive menu. 

As you would have observed, the comment wizard greatly simplifies rule creation. To gain confidence in writing more complex and interesting rules, study the list of objects exposed by the runtime (see the online help) and look through the examples of JMScript comments distributed with JStyle. Let us conclude this chapter by looking at the script code for an interesting comment. This comment is based on the idea that calling a non-private, non-final method from a constructor can lead to surprises. 

    Init(Comment) { 
        Comment.ID = 7032; 
        Comment.Representation = "JM7032"; 
        Comment.Severity = 4; 
        Comment.Classification = 8; 
        Comment.Description = "Calling a non-final/non-private method" +

                              "from the constructor is not advisable.";
    } 

    Register(RegInfo) { 
        RegInfo.Constructor = true; 
    } 

    HandleMethod(Method) { 
        //handle Constructor here 
        if(Method.enclosingclass.modifier.Final) { 
            return; 
        } 
        exprs = Method.SubExpressions(astMethodInvocationExpression); 
        foreach(methExpr in exprs) { 
            // only non-static 
            if(methExpr.Type == null) { 
                // called using this object? 
                if(methExpr.Expression == null ||  
                   methExpr.Expression.elmType == astThisExpression) { 
                    decl = methExpr.declaration; 
                    if(decl.modifier.Static || decl.modifier.Private || 
                       decl.modifier.Final)
                        { continue; } 
                    report(methExpr.fileName, methExpr.line); 
                } 
            } 
        } 
    }