javaformat.htm

JAVA CODE AND SOME USERFULL CODE

          <OL>
            <LI><A 
            href="http://www.xiaopu.com/topic.htm#Naming Compilation Units">命名编译单元</A> 

            <LI><A 
            href="http://www.xiaopu.com/topic.htm#Documenting Compilation Units">注释编译单元</A> 
            </LI></OL></LI></OL>
        <LI><A 
        href="http://www.xiaopu.com/topic.htm#Error Handling and Exceptions"><BIG><STRONG>错误处理和异常</STRONG></BIG></A> 

        <LI><A 
        href="http://www.xiaopu.com/topic.htm#Miscellaneous"><BIG><STRONG>其他标准和版本</STRONG></BIG></A> 

        <OL>
          <LI><A href="http://www.xiaopu.com/topic.htm#Reuse">复用</A> 
          <LI><A 
          href="http://www.xiaopu.com/topic.htm#Importing Classes">导入类</A> 
          <LI><A href="http://www.xiaopu.com/topic.htm#Optimizing Java Code">优化 
          Java 代码</A> 
          <LI><A 
          href="http://www.xiaopu.com/topic.htm#Writing Java Test Harnesses">编写 
          Java 测试集</A> </LI></OL>
        <LI><A 
        href="http://www.xiaopu.com/topic.htm#Patterns of Success"><BIG><STRONG>成功的模式</STRONG></BIG></A> 

        <LI><BIG><STRONG><A 
        href="http://www.xiaopu.com/topic.htm#Summary">总结</A></STRONG></BIG> 
        <OL>
          <LI><A 
          href="http://www.xiaopu.com/topic.htm#Java Naming Conventions">Java 
          命名约定</A> 
          <LI><A 
          href="http://www.xiaopu.com/topic.htm#Java Documentation Conventions">Java 
          注释约定</A> 
          <OL>
            <LI><A 
            href="http://www.xiaopu.com/topic.htm#Java Comment Types">Java 
            注释类型</A> 
            <LI><A 
            href="http://www.xiaopu.com/topic.htm#What To Document">注释哪些部分</A> 
            </LI></OL>
          <LI><A 
          href="http://www.xiaopu.com/topic.htm#Java Coding Conventions (General)">Java 
          程序设计约定（常用）</A> </LI></OL>
        <LI><BIG><STRONG><A 
        href="http://www.xiaopu.com/topic.htm#References">参考资料</A></STRONG></BIG> 

        <LI><BIG><STRONG><A 
        href="http://www.xiaopu.com/topic.htm#Glossary">词汇表</A></STRONG></BIG> 
        </LI></OL>
      <HR align=left>

      <H1><SMALL><A name=Introduction>简介</A> </SMALL><A 
      href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
      height=20 src="" width=26></A></H1>
      <P><FONT size=3>本文提供一整套编写高效可靠的 Java 
      代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。而且，通过遵循这些程序设计标准，你作为一个 Java 
      软件开发者的生产效率会有显著提高。经验证明，若从一开始就花时间编写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。</FONT></P>
      <H2><SMALL><A name=anchor5412258></A>最根本的原则：</SMALL></H2>
      <BLOCKQUOTE>
        <P><STRONG>运用常识。</STRONG>当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时侯： 
        运用常识并核实这些基本原则。这条规则比其它所有规则都重要。常识是<I>必不可少的</I>。</P></BLOCKQUOTE>
      <HR align=left>

      <H1><SMALL><A name="Coding Standards">程序设计标准</A> </SMALL><A 
      href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
      height=20 src="" width=26></A></H1>
      <BLOCKQUOTE>
        <P><FONT size=3>Java 
        的程序设计标准很重要，原因在于它将提高开发团队各成员的代码的一致性。一致性的提高会使代码更易理解，这意味着它更易开发和维护。从而降低了应用程序的总开发成本。</P>
        <P>你必须牢记的是：你的 Java 
        代码在你已离开并开始另一个项目之后，会保留相当长的一端时间。因此开发过程中一个很重要的目标就是要确保在开发成员或开发团队之间的工作可以顺利交接，不必花很大的力气便能理解已编写的代码，以便继续维护和改进以前的工作。如果代码难以理解，很有可能被废弃和重写。</FONT></P></BLOCKQUOTE>
      <BLOCKQUOTE>
        <H3><A name="Naming conventions"><FONT 
        face=Arial><I><B>命名约定</B></I></FONT></A><SMALL> </SMALL><A 
        href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
        height=20 src="" width=26></A></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <P><FONT size=3>我们将在整个标准中讨论命名约定，所以让我们先讨论几个基本点： 
        <OL><B>
          <LI>使用可以准确说明变量/字段/类的完整的英文描述符。</B>例如，采用类似 
          <B>firstName</B>，<B>grandTotal</B> 或 <B>CorporateCustomer</B> 
          这样的名字。虽然象 <B>x1</B>，<B>y1</B> 或 <B>fn</B> 
          这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。 <B>
          <LI>采用该领域的术语。</B>如果用户称他们的“客户” (clients) 为“顾客” (customers)，那么就采用术语 
          <B>Customer</B> 来命名这个类，而不用 
          <B>Client</B>。许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。 <B>
          <LI>采用大小写混合，提高名字的可读性。</B>一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写 [<A 
          href="http://www.xiaopu.com/topic.htm#KAN97">KAN97</A>]。 <B>
          <LI>尽量少用缩写，但如果一定要使用，就要谨慎地使用。</B>这意味着应该保留一个标准缩写的列表，明智地从中选取，并且在使用时保持一致。例如，想对单词“number”采用缩写，那么可从 
          <B>nbr</B>，<B>no</B> 或者 <B>num</B> 
          中选取一个，说明一下采用了哪一个（具体是哪个倒无所谓），并且只使用这一种形式。 <B>
          <LI>避免使用长名字（最好不超过 15 个字母）。 </B>虽然 
          <B>PhysicalOrVirtualProductOrService</B> 
          看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重新给它起个短一点的名字，比如象 <B>Offering</B>。 <B>
          <LI>避免使用相似或者仅在大小写上有区别的名字。</B>例如，不应同时使用变量名 <B>persistentObject</B> 和 
          <B>persistentObjects</B>，以及 <B>anSqlDatabase</B> 和 
          <B>anSQLDatabase</B>。 <B>
          <LI>避免使用下划线作为名字的首末字母。</B>以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。更重要的是，下划线经常造成麻烦而且难输入，所以尽量避免使用。</FONT> 
          </LI></OL></BLOCKQUOTE>
      <BLOCKQUOTE>
        <H3><A name="Documentation conventions"><I><B><FONT 
        face=Arial>注释约定</FONT></B></I></A><SMALL> </SMALL><A 
        href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
        height=20 src="" width=26></A></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <P><FONT size=3>我们还会对注释约定进行讨论，所以，我们先谈谈一些基本点： 
        <OL><B>
          <LI>注释应该增加代码的清晰度。</B>代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。 <B>
          <LI>如果你的程序不值得注释，那么它也很可能也不值得运行</B> [<A 
          href="http://www.xiaopu.com/topic.htm#NAG95">NAG95</A>]。 <B>
          <LI>避免使用装饰性内容，也就是说，不要使用象广告横幅那样的注释语句。</B>二十世纪六十年代和七十年代，COBOL 
          程序员们养成了画框的习惯，典型的是用星号将他们的内部注释圈起来。当然，这给他们的艺术创造欲一个发泄方式，但是坦白地说，这只是在大量浪费时间，并不能给最终的产品增加丝毫价值。要写的是清晰的代码，不是外表可爱的代码。此外，由于有些字体的显示和打印是成比例的，但有些又不是，所以无法将那些框排整齐。 
          <B>
          <LI>保持注释的简洁。</B>最好的注释应该是简单明了的注释。注释不必洋洋洒洒，只需提供足够的信息，使别人能够理解你的代码。 <B>
          <LI>先写注释，后写代码。</B>写代码注释的最好方法是在写代码之前就写注释。这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗漏注释。另一种方法是边写代码边写注释。因为注释可以使代码更易理解，所以在程序开发的过程中，也可以利用这一点。如果打算花些时间写注释，那么至少你应从这个过程中获得些什么 
          [<A href="http://www.xiaopu.com/topic.htm#AMB98">AMB98</A>] 。 <B>
          <LI>注释信息不仅要包括代码的功能，还应给出原因。</B>例如，下面例 1 中的代码显示金额在 $1,000 以上（包括 
          $1,000）的定单可给予 5% 
          的折扣。为什么要这样做呢？难道有一个商业法则规定大额定单可以得到折扣吗？这种给大额定单的特殊是有时限的呢，还是一直都这样？最初的程序设计者是否只是由于慷慨大度才这样做呢？除非它们在某个地方（或者是在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知道这些。</FONT> 
          </LI></OL>
        <BLOCKQUOTE>
          <P class=exampleheading style="MARGIN-LEFT: 0px"><FONT size=3><B>例 
          1.1</B></FONT></P></BLOCKQUOTE>
        <P class=example><FONT size=3>if (grandTotal &gt;= 1000.00)</P>
        <P class=example>{</P>
        <BLOCKQUOTE>
          <P class=example>grandTotal = grandTotal * 0.95;</P></BLOCKQUOTE>
        <P class=example>}</P></FONT>
        <BLOCKQUOTE>
          <H4><FONT face=Arial><A name="Types of Java Comments">Java 
          注释语句类型</A></FONT><SMALL> </SMALL><A 
          href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
          height=20 src="" width=26></A></H4>
          <P><FONT size=3>Java 有三种注释语句风格：以 /** 开始， */ 结束的文档注释，以 /* 开始，以 */ 
          结束的C语言风格注释，以及以 // 
          开始，代码行末尾结束的单行注释。下表是对各类注释语句<U>建议</U>用法的一个概括，也给出了几个例子。</FONT></P>
          <TABLE border=1 cellPadding=7 cellSpacing=1 width=590>
            <TBODY>
            <TR>
              <TD bgColor=#ffffff vAlign=top 
                width="21%"><B><BIG>注释语句类型</BIG></B></TD>
              <TD bgColor=#ffffff vAlign=top 
              width="40%"><B><BIG>用法</BIG></B></TD>
              <TD bgColor=#ffffff vAlign=top 
              width="40%"><B><BIG>示例</BIG></B></TD></TR>
            <TR>
              <TD vAlign=top width="21%"><STRONG><FONT 
                size=3>文档注释</FONT></STRONG></TD>
              <TD vAlign=top width="40%"><FONT 
                size=3>在接口、类、成员函数和字段声明之前紧靠它们的位置用文档注释进行说明。文档注释由 <I>javadoc</I> 
                处理，为一个类生成外部注释文档，如下所示。</FONT></TD>
              <TD vAlign=top width="40%"><FONT size=3>/** 
                <P>Customer （顾客）.顾客是指作为我们的服务及产品的销售对象的任何个人或组织。</P>
                <P>@author S.W. Ambler</P>
                <P>*/</FONT></P></TD></TR>
            <TR>
              <TD vAlign=top width="21%"><STRONG><FONT size=3><EM>C</EM> 
                语言风格注释</FONT></STRONG></TD>
              <TD vAlign=top width="40%"><FONT size=3>采用 C 
                语言风格的注释语句将无用的代码注释掉。保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。</FONT></TD>
              <TD vAlign=top width="40%"><FONT size=3>/* 
                <P>这部分代码已被它前面的代码替代，所以于 1999 年6 月 4 日被 B. Gustafsson 
                注释掉。如果两年之后仍未用这些代码，将其删除。</P>
                <P>. . . （源代码）</P>
                <P>*/</FONT></P></TD></TR>
            <TR>
              <TD vAlign=top width="21%"><STRONG><FONT 
                size=3>单行注释</FONT></STRONG></TD>