JAVA应用技术之编码规范(codetemplate,checkstyle)

1.CodeTemplate模板      
      在日常开发代码的过程中,我们往往需要一个编码规范,比如注释规范,不然,每个人写得不一样,不利于公司资产或者说代码库管理,让后期代码维护造成很大影响。下面我根据我们公司给的那个JAVA编码规范制作成一个codetemplate模板供大家参考,下面是它的代码内容,稍后我来说明如何将其将入eclipse代码库中。
下面是我配置后导出的codetemplate.xml,仅供参考:
  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <templates>
  3.         <template autoinsert="false" context="gettercomment_context"
  4.                 deleted="false" description="Comment for getter method" enabled="true"
  5.                 id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/**
  6.                 *
  7.                 ${bare_field_name}
  8.                 * @return the ${bare_field_name}
  9.                 */
  10.         </template>
  11.         <template autoinsert="false" context="settercomment_context"
  12.                 deleted="false" description="Comment for setter method" enabled="true"
  13.                 id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/**
  14.                 *
  15.                 @param ${param} 要设置的 ${bare_field_name}
  16.                 **/</template>
  17.         <template autoinsert="false" context="constructorcomment_context"
  18.                 deleted="false" description="Comment for created constructors"
  19.                 enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment"
  20.                 name="constructorcomment">/**
  21.                 * <p>Title: </p>
  22.                 * <p>Description: </p>
  23.                 * ${tags}
  24.                 */</template>
  25.         <template autoinsert="false" context="filecomment_context"
  26.                 deleted="false" description="Comment for created Java files" enabled="true"
  27.                 id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment">
  28.                 /*
  29.                 * Copyright (C) 2011 GZ-ISCAS Inc., All Rights Reserved.
  30.                 */</template>
  31.         <template autoinsert="false" context="typecomment_context"
  32.                 deleted="false" description="Comment for created types" enabled="true"
  33.                 id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">/**
  34.                 * @ClassName: ${type_name}
  35.                 * @Description: ${todo}(这里用一句话描述这个类的作用)
  36.                 * @author ????? Email: [email protected]
  37.                 * @date ${date} - ${time}
  38.                 *@version : 1.0
  39.                 * ${tags}
  40.                 */</template>
  41.         <template autoinsert="false" context="fieldcomment_context"
  42.                 deleted="false" description="Comment for fields" enabled="true"
  43.                 id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/**
  44.                 * @Fields ${field} : ${todo}(用一句话描述这个变量表示什么)
  45.                 */</template>
  46.         <template autoinsert="false" context="methodcomment_context"
  47.                 deleted="false" description="Comment for non-overriding methods"
  48.                 enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment"
  49.                 name="methodcomment">/**
  50.                 * @Title: ${enclosing_method}
  51.                 * @Description: ${todo}(这里用一句话描述这个方法的作用)
  52.                 * @param ${tags} 设定文件
  53.                 * @return ${return_type} 返回类型
  54.                 * @throws
  55.                 */</template>
  56.         <template autoinsert="false" context="overridecomment_context"
  57.                 deleted="false" description="Comment for overriding methods" enabled="true"
  58.                 id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/* (非
  59.                 Javadoc)
  60.                 * <p>Title: ${enclosing_method}</p>
  61.                 * <p>Description: </p>
  62.                 * ${tags}
  63.                 * ${see_to_overridden}
  64.                 */</template>
  65.         <template autoinsert="false" context="delegatecomment_context"
  66.                 deleted="false" description="Comment for delegate methods" enabled="true"
  67.                 id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/**
  68.                 *
  69.                 ${tags}
  70.                 * ${see_to_target}
  71.                 */</template>
  72.         <template autoinsert="true" context="newtype_context" deleted="false"
  73.                 description="Newly created files" enabled="true"
  74.                 id="org.eclipse.jdt.ui.text.codetemplates.newtype" name="newtype">${filecomment}
  75.                 ${package_declaration}

  76.                 ${typecomment}
  77.                 ${type_declaration}</template>
  78.         <template autoinsert="true" context="classbody_context"
  79.                 deleted="false" description="Code in new class type bodies" enabled="true"
  80.                 id="org.eclipse.jdt.ui.text.codetemplates.classbody" name="classbody">
  81.         </template>
  82.         <template autoinsert="true" context="interfacebody_context"
  83.                 deleted="false" description="Code in new interface type bodies"
  84.                 enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.interfacebody"
  85.                 name="interfacebody">
  86.         </template>
  87.         <template autoinsert="true" context="enumbody_context"
  88.                 deleted="false" description="Code in new enum type bodies" enabled="true"
  89.                 id="org.eclipse.jdt.ui.text.codetemplates.enumbody" name="enumbody">
  90.         </template>
  91.         <template autoinsert="true" context="annotationbody_context"
  92.                 deleted="false" description="Code in new annotation type bodies"
  93.                 enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.annotationbody"
  94.                 name="annotationbody">
  95.         </template>
  96.         <template autoinsert="true" context="catchblock_context"
  97.                 deleted="false" description="Code in new catch blocks" enabled="true"
  98.                 id="org.eclipse.jdt.ui.text.codetemplates.catchblock" name="catchblock">// ${todo}
  99.                 Auto-generated catch block
  100.                 ${exception_var}.printStackTrace();</template>
  101.         <template autoinsert="true" context="methodbody_context"
  102.                 deleted="false" description="Code in created method stubs" enabled="true"
  103.                 id="org.eclipse.jdt.ui.text.codetemplates.methodbody" name="methodbody">// ${todo}
  104.                 Auto-generated method stub
  105.                 ${body_statement}</template>
  106.         <template autoinsert="true" context="constructorbody_context"
  107.                 deleted="false" description="Code in created constructor stubs"
  108.                 enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorbody"
  109.                 name="constructorbody">${body_statement}
  110.                 // ${todo} Auto-generated constructor stub</template>
  111.         <template autoinsert="true" context="getterbody_context"
  112.                 deleted="false" description="Code in created getters" enabled="true"
  113.                 id="org.eclipse.jdt.ui.text.codetemplates.getterbody" name="getterbody">return
  114.                 ${field};</template>
  115.         <template autoinsert="true" context="setterbody_context"
  116.                 deleted="false" description="Code in created setters" enabled="true"
  117.                 id="org.eclipse.jdt.ui.text.codetemplates.setterbody" name="setterbody">${field} =
  118.                 ${param};</template>
  119. </templates>
复制代码

导入的时候打开eclipse,在windows菜单下选中Preferences,打开如下对话框,



这样就先成导入模板操作了。




2.使用checkstyle插件


安装过程略,详细查看杰哥的PPT文档,下面说一下如何配置和使用checkstyle插件。


参考网上,并参照JAVA规范,如下所示:


checkstyle.xml文件:



  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3. /*
  4. * Copyright 2001-2004 The Apache Software Foundation.
  5. *
  6. * Licensed under the Apache License, Version 2.0 (the "License");
  7. * you may not use this file except in compliance with the License.
  8. * You may obtain a copy of the License at
  9. *
  10. *      http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing, software
  13. * distributed under the License is distributed on an "AS IS" BASIS,
  14. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15. * See the License for the specific language governing permissions and
  16. * limitations under the License.
  17. */
  18. -->

  19. <!DOCTYPE module PUBLIC
  20.     "-//Puppy Crawl//DTD Check Configuration 1.1//EN"
  21.     "http://www.puppycrawl.com/dtds/configuration_1_1.dtd">
  22. <module name="Checker">

  23.     <!--
  24.       javadoc部分的检测都属于第二等级,建议使用。
  25.       -->
  26.     <module name="PackageHtml">
  27.         <property name="severity" value="warning"/>
  28.     </module>

  29.     <!--
  30.       每个源文件的结尾,必须有一个空行。
  31.       这部分由代码美化器控制。
  32.       
  33.     <module name="NewlineAtEndOfFile"/>
  34.         -->
  35.     <!--
  36.       翻译
  37.       -->
  38.     <module name="Translation"/>

  39.     <module name="TreeWalker">

  40.         <property name="cacheFile" value="${checkstyle.cache.file}"/>
  41.         <property name="tabWidth" value="4"/>


  42.         <!--
  43.           Javadoc comments
  44.           javadoc部分的检测都属于第二等级,建议使用。
  45.           -->
  46.         <module name="JavadocMethod">
  47.             <property name="severity" value="warning"/>
  48.         </module>
  49.         <module name="JavadocType">
  50.             <property name="severity" value="warning"/>
  51.         </module>
  52.         <module name="JavadocVariable">
  53.             <property name="severity" value="warning"/>
  54.         </module>
  55.         <module name="JavadocStyle">
  56.             <property name="severity" value="warning"/>
  57.         </module>


  58.         <!--
  59.           Naming conventions
  60.           命名方式属于第一等级,一定要保证统一的命名格式。
  61.           -->
  62.         <module name="MemberName" />
  63.         <module name="ConstantName"/>
  64.         <module name="LocalFinalVariableName"/>
  65.         <module name="LocalVariableName"/>
  66.         <module name="MethodName"/>
  67.         <module name="PackageName"/>
  68.         <module name="ParameterName"/>
  69.         <module name="StaticVariableName"/>
  70.         <module name="TypeName"/>


  71.         <!--
  72.           Headers
  73.           -->


  74.         <!--
  75.           Imports
  76.           强制要求import不能使用*,不能使用sun开头的包,不能重复import,也不能有没用到的包。
  77.           -->
  78.         <module name="AvoidStarImport"/>
  79.         <module name="IllegalImport"/>
  80.         <module name="RedundantImport"/>
  81.         <module name="UnusedImports"/>


  82.         <!--
  83.           Size Violations
  84.           每行不得超过120个字符,@version和@see部分除外,这两部分有可能超过120个字符。
  85.           文件长度不能超过2000,方法长度不能超过150,内部类不能超过20行,方法的参数不能多于7个。
  86.           这几个也属于建议级别。
  87.           -->
  88.         <module name="LineLength">
  89.             <property name="max" value="120" />
  90.             <property name="ignorePattern" value="@version|@see"/>
  91.         </module>
  92.         <module name="FileLength">
  93.             <property name="severity" value="warning"/>
  94.         </module>
  95.         <module name="MethodLength">
  96.             <property name="severity" value="warning"/>
  97.         </module>
  98.         <module name="ParameterNumber">
  99.             <property name="severity" value="warning"/>
  100.         </module>
  101.         <module name="AnonInnerLength">
  102.             <property name="severity" value="warning"/>
  103.         </module>


  104.         <!--
  105.           Whitespace
  106.           for循环的空白,用空白包裹操作符,不允许使用\t制表符
  107.           使用代码美化器实现,这些是必须遵守的。
  108.           -->
  109.         <module name="EmptyForIteratorPad"/>
  110.         <module name="OperatorWrap"/>
  111.         <module name="ParenPad"/>
  112.         <module name="TabCharacter"/>
  113.         <module name="MethodParamPad"/>


  114.         <!--
  115.           Modifiers
  116.           修饰符必须按顺序排列,不允许重复。
  117.           -->
  118.         <module name="ModifierOrder"/>
  119.         <module name="RedundantModifier"/>


  120.         <!--
  121.           Block checks
  122.           禁止出现块嵌套,if,else即使只有一行数据,也要写上大括号。
  123.           emptyblock可以提醒开发者,不要忘记实现block中的内容。
  124.           -->
  125.         <module name="LeftCurly"/>
  126.         <module name="RightCurly"/>
  127.         <module name="AvoidNestedBlocks"/>
  128.         <module name="EmptyBlock"/>
  129.         <module name="NeedBraces">
  130.             <property name="tokens" value="LITERAL_IF, LITERAL_ELSE"/>
  131.         </module>


  132.         <!--
  133.           Coding
  134.           不要重复检测同一条件,不能用空的语句,检测equals和hashcode配对,
  135.           除了setter和constructor其他方法的参数和类变量不能同名,
  136.           不能使用性能不高的初始化方法,不能在参数表中使用赋值语句,
  137.           不能使用无法确定含义的数字,除了-1,0,1,2以外,
  138.           switch必须包含default,使用简单boolean表达式和返回表达式。
  139.           -->
  140.         <module name="DoubleCheckedLocking"/>
  141.         <module name="EmptyStatement"/>
  142.         <module name="EqualsHashCode"/>
  143.         <module name="HiddenField">
  144.             <property name="ignoreConstructorParameter" value="true"/>
  145.             <property name="ignoreSetter" value="true"/>
  146.         </module>
  147.         <module name="IllegalInstantiation"/>
  148.         <module name="InnerAssignment"/>
  149.         <module name="MagicNumber"/>
  150.         <module name="MissingSwitchDefault"/>
  151.         <module name="RedundantThrows"/>
  152.         <module name="SimplifyBooleanExpression"/>
  153.         <module name="SimplifyBooleanReturn"/>


  154.         <!--
  155.           Class Design
  156.           interface中必须定义方法,不能只有变量。
  157.           -->
  158.         <module name="FinalClass"/>
  159.         <module name="HideUtilityClassConstructor"/>
  160.         <module name="InterfaceIsType"/>
  161.         <module name="VisibilityModifier">
  162.             <property name="protectedAllowed" value="true"/>
  163.         </module>

  164.         <!--
  165.           Duplicate code
  166.           -->

  167.         <!--
  168.           Metrics
  169.           DAC不大于7,
  170.           CFO不大于20,
  171.           CC不大于10,
  172.           NPath不大于200,
  173.           布尔表达式,运算符不超过3个
  174.           -->
  175.         <module name="ClassDataAbstractionCoupling">
  176.             <property name="severity" value="info"/>
  177.         </module>
  178.         <module name="ClassFanOutComplexity">
  179.             <property name="severity" value="info"/>
  180.         </module>
  181.         <module name="CyclomaticComplexity">
  182.             <property name="severity" value="info"/>
  183.         </module>
  184.         <module name="NPathComplexity">
  185.             <property name="severity" value="info"/>
  186.         </module>
  187.         <module name="BooleanExpressionComplexity">
  188.             <property name="severity" value="info"/>
  189.         </module>


  190.         <!--
  191.           Miscellaneous other checks.
  192.           行末不能有空格,符合TODO:形式的注释会被提示出来
  193.           用于测试的main函数(没有注释),应该删除
  194.           定义long应该使用“L”而不是“l”
  195.           使用java格式的数组类型定义
  196.           -->
  197.         <module name="ArrayTypeStyle"/>
  198.         <module name="GenericIllegalRegexp">
  199.             <property name="format" value="\s+[        DISCUZ_CODE_1        ]quot;/>
  200.             <property name="message" value="Line has trailing spaces."/>
  201.         </module>
  202.         <module name="TodoComment"/>
  203.         <module name="UpperEll"/>
  204.         <module name="UncommentedMain"/>

  205.     </module>

  206. </module>
复制代码

然后在顶级pom.xml文件中加入如下代码:

下面这个是打印报表所需要的插件配置。


  1. <reporting>
  2.                 <plugins>
  3.                         <plugin>
  4.                                 <groupId>org.codehaus.mojo</groupId>
  5.                                 <artifactId>cobertura-maven-plugin</artifactId>
  6.                                 <version>2.4</version>
  7.                                 <inherited>true</inherited>
  8.                         </plugin>
  9.                         <plugin>
  10.                                 <groupId>org.apache.maven.plugins</groupId>
  11.                                 <artifactId>maven-javadoc-plugin</artifactId>
  12.                                 <version>2.6.1</version>
  13.                                 <configuration>
  14.                                         <encoding>UTF-8</encoding>
  15.                                 </configuration>
  16.                                 <inherited>true</inherited>
  17.                         </plugin>
  18.                         
  19.                         <plugin>
  20.                                         <groupId>org.apache.maven.plugins</groupId>
  21.                                         <artifactId>maven-checkstyle-plugin</artifactId>
  22.                                         <version>2.8</version>
  23.                                         <configuration>
  24.                                           <configLocation>F:/project/sems/cn.ac.iscas.gz.sems/checkstyle.xml</configLocation>
  25.                                           <headerLocation>../LICENSE.txt</headerLocation>
  26.                                         </configuration>
  27.                            </plugin>
  28.                         
  29.                 </plugins>
  30.         </reporting>
复制代码


然后是<plugins>插件的配置.


  1. <plugins>            
  2.      <plugin>

  3.                       <groupId>org.apache.maven.plugins</groupId>
  4.                         <artifactId>maven-checkstyle-plugin</artifactId>
  5.                           <version>2.8</version>
  6.                            <dependencies>
  7.                             <dependency>
  8.                                 <groupId>com.example.whizbang</groupId>
  9.                                       <artifactId>build-tools</artifactId>
  10.                                        <version>1.0</version>
  11.                                         </dependency>
  12.                              </dependencies>

  13.       </plugin>               
  14.   </plugins>
复制代码


最后在命令行中输入                 
                  mvn site  或者   mvn compile checkstyle:checkstyle

如果你要撤销的话,用 mvn clean site
这样就会在target\site 下面生成报表文件,如下所示






3.一些理论知识

     Checkstyle是一个开发工具,可以帮助编程人员编写符合编码规范的java 代码。程序员都非常讨厌程序的check工作,checkstyle能够自动地完成这项烦琐但又非常重要的工作,从而节省了的程序员的时间,也提高了检查的质量。Checkstyle已经成了加强编码规范的首选工具。


(完,待续....)


参考网址:

http://code.google.com/p/testcq/wiki/CheckStyleRules

http://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html


http://topinking.iteye.com/blog/218481


http://darkranger.iteye.com/blog/1130283

你可能感兴趣的:(java,Module,javadoc,Constructor,dependencies,methods)