| Check and feel better about your code!

(c) 1999-2004 by Ralph Jocham (rjocham72@netscape.net)
JCSC is released under the terms of the GNU General Public License

JCSC Overview Performed Checks Testimonials Documentation Usage Rules Update JavaDoc JCSC of JCSC Extensions Rules Editor UI Ant IntelliJ IDEA CruiseControl How to get Download Installation Developers General Project Page CVS Repository Screenshots Changelog Donate
|  | # Documentation ## Usage ### Command Line After you have installed it, you can use it like any other command. Be aware that the command line `jcsc` tool can not be used to scan a whole folder recursively; for that you have to use the JCSC Ant task. If you use the `-r` flag, JCSC looks first into the JCSC_HOME/rules folder, if it is not found there it tries to find it using the absolute path. jcsc [option] <file>|stream Replace jcsc with either jcsc.bat or jcsc.sh depending on your platform with the option being: -h : show the help -r <rule> :the rule file is read from the file system -j <rule> :the rule file is read from the jcsc.jar file #### Example Output $ jcsc -r jcsc.jcsc.xml JCSCTask.java Violations: JCSCTask.java:55:100:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:56:92:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:147:50:conditional expression (?:) are not allowed:ConditionalExpression:3 JCSCTask.java:158:55:conditional expression (?:) are not allowed:ConditionalExpression:3 JCSCTask.java:169:56:conditional expression (?:) are not allowed:ConditionalExpression:3 JCSCTask.java:262:86:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:290:81:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:334:91:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:218:empty catch block, this is normally an error:EmptyCatchBlock:3 JCSCTask.java:225:empty finally block, this is normally an error:EmptyFinallyBlock:3 JCSCTask.java:229:method return 'boolean' and starts with 'get' it should start with 'is' or 'has':RegExpPrefixForMethodReturningboolen:3 JCSCTask.java:231:A space after statement keyword 'while' is mandatory:SpaceAfterStatementKeywoard:3 JCSCTask.java:231:statement following 'while' is not in '{' ... '}' which is source of many errors:BraceAroundSingleLineStatement:3 JCSCTask.java:340:96:line is too long 0..80 characters are allowed:LineLength:3 JCSCTask.java:346:91:line is too long 0..80 characters are allowed:LineLength:3 [...] JCSCTask.java:1070:15:conditional expression (?:) are not allowed:ConditionalExpression:3 JCSCTask.java:1077:15:conditional expression (?:) are not allowed:ConditionalExpression:3 46 violation(s) found Metrics: 84:37:JCSCTask.setRules():NCSS-2:CCN-1 94:35:JCSCTask.setFile():NCSS-4:CCN-1 107:51:JCSCTask.setStartpackage():NCSS-4:CCN-2 122:59:JCSCTask.setResultsformatter():NCSS-2:CCN-1 133:37:JCSCTask.setDestdir():NCSS-3:CCN-1 145:39:JCSCTask.setWorstCount():NCSS-2:CCN-1 156:40:JCSCTask.setStartDate():NCSS-2:CCN-1 167:41:JCSCTask.setFailValue():NCSS-2:CCN-1 176:37:JCSCTask.addFileSet():NCSS-3:CCN-1 187:30:JCSCTask.getFiles():NCSS-18:CCN-5 228:24:JCSCTask.execute():NCSS-7:CCN-2 244:40:JCSCTask.getFile():NCSS-5:CCN-3 257:43:JCSCTask.checkForTooManyViolations():NCSS-3:CCN-3 267:32:JCSCTask.parameterCheck():NCSS-23:CCN-10 327:37:JCSCTask.batchParameterCheck():NCSS-13:CCN-4 354:53:JCSCTask.throwExceptionIfError():NCSS-3:CCN-3 368:40:JCSCTask.executeFile():NCSS-6:CCN-3 391:44:JCSCTask.executeFiles():NCSS-7:CCN-2 409:49:JCSCTask.parseSingleFileFromBatch():NCSS-11:CCN-3 435:53:JCSCTask.convertAuthors2String():NCSS-8:CCN-3 458:40:JCSCTask.parseSingleFile():NCSS-10:CCN-2 483:33:JCSCTask.isFileSetSet():NCSS-2:CCN-1 495:42:JCSCTask.isResultsFormatterSet():NCSS-2:CCN-1 506:38:JCSCTask.isStartPackageSet():NCSS-2:CCN-1 518:33:JCSCTask.isDestDirSet():NCSS-2:CCN-1 529:35:JCSCTask.isStartDateSet():NCSS-2:CCN-1 540:35:JCSCTask.isFailValueSet():NCSS-2:CCN-1 545:51:JCSCTask.createResultsFormatter():NCSS-9:CCN-3 568:25:JCSCTask.getRules():NCSS-10:CCN-3 599:48:JCSCTask.getOutputFileName():NCSS-8:CCN-1 619:45:JCSCTask.getPackageName():NCSS-7:CCN-1 638:43:JCSCTask.getClassName():NCSS-5:CCN-1 647:34:JCSCTask.convertDate2Long():NCSS-13:CCN-1 670:26:JCSCTask.getPackageMap():NCSS-2:CCN-1 682:50:JCSCTask.add2PackageMap():NCSS-19:CCN-2 720:66:JCSCTask.add2IndexMap():NCSS-9:CCN-2 745:76:JCSCTask.add2ViolationsMap():NCSS-2:CCN-1 755:52:JCSCTask.writeConsoleOverview():NCSS-10:CCN-1 838:55:JCSCTask.Comparator.compare():NCSS-4:CCN-1 775:26:JCSCTask.writeXML():NCSS-56:CCN-5 873:41:JCSCTask.writePackageOverviewXml():NCSS-23:CCN-3 919:34:JCSCTask.writeOverviewXml():NCSS-21:CCN-2 953:68:JCSCTask.writeWorstClassesXml():NCSS-10:CCN-2 971:32:JCSCTask.getPackageCount():NCSS-2:CCN-1 976:30:JCSCTask.getClassCount():NCSS-7:CCN-2 991:31:JCSCTask.getMethodCount():NCSS-7:CCN-2 1006:34:JCSCTask.getViolationCount():NCSS-7:CCN-2 1021:29:JCSCTask.getNCSSCount():NCSS-7:CCN-2 1036:38:JCSCTask.getUnitTestClassCount():NCSS-7:CCN-2 1051:33:JCSCTask.getUnitTestCount():NCSS-7:CCN-2 1066:49:JCSCTask.calculateAvgViolationsPerNcss():NCSS-2:CCN-1 1073:50:JCSCTask.calculateAvgViolationsPerClass():NCSS-2:CCN-1 Total NCSS count : 449 Total Methods count : 52 Unit Test Class count : 0 Unit Tests count : 0 ### Rules Editor Just run the `ruleseditor` script in the JCSC_HOME/bin folder. Per default you read the default settings which are stored in the jar file. You can modify these and save them into a file. Also you can open an existing file, either from within the UI or by passing the rules file name as an argument. ### Ant If you are familar with `Ant` then read this. Otherwise checkout the Ant website at http://jakarta.apache.org/ant/ #### Example Output See example 2 from the 'this' link above. `$ ant -buildfile jcsc.xml all /cygdrive/e/jakarta-ant-1.5/lib/xml-apis.jar:/cygdrive/e/jakarta-ant-1.5/lib/xercesImpl.jar:/cygdriv e/e/jakarta-ant-1.5/lib/optional.jar:/cygdrive/e/jakarta-ant-1.5/lib/gnu-regexp.jar:/cygdrive/e/jaka rta-ant-1.5/lib/ant.jar:/cygdrive/e/jakarta-ant-1.5/lib/JCSC.jar:/cygdrive/e/jaxp-1.1/jaxp.jar:/cygd rive/e/jaxp-1.1/crimson.jar:/cygdrive/e/jaxp-1.1/xalan.ja:/cygdrive/e/jakarta-ant/lib/ant.jar:/cygdr ive/e/jakarta-ant/lib/jakarta-ant-1.4.1-optional.jar:/cygdrive/c/java/jdk1.3/lib/tools.jar e:\jakarta-ant-1.5\lib\xml-apis.jar;e:\jakarta-ant-1.5\lib\xercesImpl.jar;e:\jakarta-ant-1.5\lib\opt ional.jar;e:\jakarta-ant-1.5\lib\gnu-regexp.jar;e:\jakarta-ant-1.5\lib\ant.jar;e:\jakarta-ant-1.5\li b\JCSC.jar;e:\jaxp-1.1\jaxp.jar;e:\jaxp-1.1\crimson.jar;e:\jaxp-1.1\xalan.ja;e:\jakarta-ant\lib\ant. jar;e:\jakarta-ant\lib\jakarta-ant-1.4.1-optional.jar Buildfile: jcsc.xml all: [jcsc] Package Count: 10 [jcsc] Class Count: 26 [jcsc] Methods Count: 281 [jcsc] Total Violations Count : 153 [jcsc] Avg Violations per Class: 5.8846154 [jcsc] Total NCSS Count: 3430 [jcsc] Avg Violations per NCSS: 0.044606414 [jcsc] Unit Test Class Count: 2 [jcsc] Unit Tests Count: 83 BUILD SUCCESSFUL` The resulting XML files can be found in the folder specified by the Ant task. The XML can be viewed via XSL compliant browsers.Tested with Mozilla 1+ and IE6. IE needs to have the SP1 in order to work correctly. If you have problems and not IE SP1 then open your IE browser and choose `Tools->Windows Update` from the menu. The web page guides you how to do the update. ### Metrics NCSS NCSS is an acronym for Non Commenting Source Statements. This number represents pure functionality code lines in a source file. Comparing this number and the violations count, the quality can be eassier assest. (for more informations on this topic go here) CCN CCN is an acronym for Cyclomatic Complexity Number. This number indicates the number in how many branches the flow is split. Each method has a CCN of 1 per default. (for more information on this topic go here) ## Rules The rules for checking a stored in a XML file. This XML is easy to read: 01 <jcsc version="__0.95__" date="2003-06-18 09:01:13"> 02 <rules> 03 <rule name="CFProRegExp" category="Field" enabled="true"> 04 <type>regexp</type> 05 <value>s[A-Z0-9][\w\d]*</value> 06 <severity>3</severity> 07 </rule> 08 <rule name="NestedTypeBlockPlaceRule" category="General" enabled="true"> 09 <type>multichoice</type> 10 <choices> 11 <choice>Beginning of Class</choice> 12 <choice>End of Class</choice> 13 </choices> 14 <value>End of Class</value> 15 <severity>3</severity> 16 </rule> 17 ... 18 </rules> 19 </jcsc> Line 01: start of the JCSC rules file showing the version of JCSC and the timestamp when it was saved for the last time Line 02: starting of the rules block Line 03: start of a rule showing the name (maps to the key on the Ruleseditor UI) the category it belongs to and whether it is enabled Line 04: shows the type; in this case a regular expression Line 05: shows the value of the specified type Line 06: shows the severity; each rule can have a severity from 1-5 with 1=lowest and 5=highest Line 07: end of rule Line 08: start of a rule Line 09: show the type; in this case multichoice (ie combo box) this rule requires a block of choices Line 10: start of choices block Line 11: choice Line 12: choice Line 13: end of choices block Line 14: shows the value which has to be on of the choices block Line 15: shows the severity Line 16: end of rule Line 17: more rules Line 18: end of rules block Line 19: end of JCSC rules file Allowed types (Lines 04,09) are: regexp: value is a regexp string regexp-multinline: value is a regexp string spanning several lines integer: value is a integer number boolean: values are either true or false multichoice: value is on of the choices You can place your own rules into the jcsc.jar file and access them with the -j option. ## Update ### General There are multiple ways to update you current JCSC installation, here is one: rename the `JCSC` folder to which `JCSC_HOME` points to `oldJCSC` download the latest version expand it to the location `JCSC_HOME` is pointing move custom files from `oldJCSC` to `JCSC` backup or delete `oldJCSC` folder ### Rules File #### 0.96 to 0.97 No changes to the rules file. #### 0.95 to 0.96 The <priority>/</priority> tag has been renamed to <severity> ie. </severity>. In your rules XML files replace all occurences of <priority> with <severity> and </priority> with </severity>. #### 0.94 to 0.95 In the JCSC_HOME/bin folder is a convert script. Run this to convert the .jcsc properties file into a .jcsc.xml file. Usage for Win: convert.bat <old>.jcsc Usage for Nix: convert.sh <old>.jcsc A <old>.jcsc.xml usable for JCSC 0.95will be created #### 0.93 to 0.94 Open the existing one and set the new rules and save them. #### 0.92 to 0.93 The best thing to do is the following: Diff (with any diff program) the old `JCSC_HOME/rules/jcsc.jcsc` file with the new one (i.e version 0.92 with 0.93); this gives you an overview about what rules have been added and which have been moved or modified. Using this knowledge you then can modify your own `.jcsc` file. Sorry for this painfull process -- a migration tool would be nice ;) Last updated on 2004-04-24 21:51