javaformat.htm

JAVA CODE AND SOME USERFULL CODE

      <BLOCKQUOTE><FONT size=3>
        <P>这个命名约定由 Sun 公司设定，必须严格遵守。</FONT></P></BLOCKQUOTE><FONT face=Arial><I><B>
      <H2><A 
      name="Member Function Visibility">成员函数的可见性</A></B></I></FONT><SMALL> 
      </SMALL><A href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 
      border=0 height=20 src="" width=26></A></H2>
      <BLOCKQUOTE>
        <P><FONT size=3>良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有 
        (public)，就定义为保护 (protected)；没必要保护 (protected)，就定义为私有 
        (private)。</P></FONT>
        <TABLE border=1 cellPadding=7 cellSpacing=1 width=590>
          <TBODY>
          <TR>
            <TD bgColor=#ffffff vAlign=top 
width="14%"><B><BIG>可见性</BIG></B></TD>
            <TD bgColor=#ffffff vAlign=top width="43%"><B><BIG>说明</BIG></B></TD>
            <TD bgColor=#ffffff vAlign=top 
            width="43%"><B><BIG>正确用法</BIG></B></TD></TR>
          <TR>
            <TD vAlign=top width="14%"><STRONG><FONT 
              size=3>public</FONT></STRONG></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>公有成员函数可被任何其它对象和类的成员函数调用。</FONT></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>当该成员函数必须被该函数所在的层次结构之外的其他对象和类在访问时。</FONT></TD></TR>
          <TR>
            <TD vAlign=top width="14%"><STRONG><FONT 
              size=3>protected</FONT></STRONG></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>被保护的成员函数可被它所在的类或该类的子类的任何成员函数调用。</FONT></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>当该成员函数提供的行为被它所在类的层次结构内部而非外部需要时。</FONT></TD></TR>
          <TR>
            <TD vAlign=top width="14%"><STRONG><FONT 
              size=3>private</FONT></STRONG></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>私有成员函数只可以被该类所在的其它成员函数调用，该类的子类不可以调用。</FONT></TD>
            <TD vAlign=top width="43%"><FONT 
              size=3>当该成员函数所提供的行为明确针对定义它的类时。私有成员函数常常是重新分配要素的结果。重新分配要素又叫“重组”，指类内其它成员函数封装某一个特定行为的做法。</FONT></TD></TR></TBODY></TABLE></BLOCKQUOTE>
      <H2><A name="Documenting Member Functions"><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></H2>
      <BLOCKQUOTE><FONT size=3>
        <P>如何注释一个成员函数常常成为判断函数是否可被理解，进而可维护和可扩展的决定性因素。</FONT></P></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial>
        <H3>成员函数的函数头</FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE>
          <P><FONT size=3>每一个 Java 
          成员函数都应包含某种称之为“成员函数文档”的函数头。这些函数头在源代码的前面，用来记录所有重要的有助于理解函数的信息。 
          这些信息包含但不仅仅局限于以下内容： 
          <OL><B>
            <LI>成员函数做什么以及它为什么做这个</B>。通过给一个成员函数加注释，让别人更加容易判断他们是否可以复用代码。注释出函数为什么做这个可以让其他人更容易将你的代码放到程序的上下文中去。也使其他人更容易判断是否应该对你的某一段代码加以修改（有可能他要做的修改与你最初为什么要写这一段代码是相互冲突的）。 
            <B>
            <LI>哪些参数必须传递给一个成员函数</B>。还必须说明，如果带参数，那么什么样的参数必须传给成员函数，以及成员函数将怎样使用它们。这个信息使其他程序员了解应将怎样的信息传递给一个成员函数。在 
            (第 1.4.2 节“快速浏览 javadoc”) 中讨论的 <I>javadoc</I> <I>@param</I> 
            标识便用于该目的。 <B>
            <LI>成员函数返回什么</B>。如果成员函数有返回值，则应注释出来，这样可以使其他程序员正确地使用返回值/对象。在 (第 
            1.4.2节“快速浏览 javadoc”) 里讨论的 <I>javadoc</I> <I>@return</I> 标识便用于此目的。 
            <B>
            <LI>已知的问题。</B>成员函数中的任何突出的问题都应说明，以便让其他程序开发者了解该成员函数的弱点和难点。如果在一个类的多个成员函数中都存在着同样的问题，那么这个问题应该写在类的说明里。 
            <B>
            <LI>任何由某个成员函数抛出的异常。</B>应说明成员函数抛出的所有异常，以便使其他程序员明白他们的代码应该捕获些什么。在 (第 
            1.4.2节“快速浏览 javadoc”) 中讨论的 <I>javadoc</I> <I>@exception</I> 
            标识便用于此目的。 <B>
            <LI>可见性决策。</B>如果你觉得你对于一个成员函数可见性的选择会遭到别人的质疑，例如可能你将一个成员函数设为公共的，但是却没有任何对象调用该成员函数，那么应说明你的决定。这将帮助其他开发者了解你的想法，使他们不必浪费时间操心考虑你为什么要选择一种有疑问的东西。 
            <B>
            <LI>成员函数是如何改变对象的</B>。若一个成员函数修改了一个对象，例如一个银行帐户的成员函数 <B>withdraw()</B> 
            修改了帐户余额，那么就需要说明。 这种信息必须给出，使其他 Java 程序员能准确地知道一个成员函数调用将如何影响目标对象。 <B>
            <LI>避免使用含有信息的函数头</B>。比如说作者、电话、创建和修改日期、单元（或者文件名）的位置，因为这些信息很快就会过时。将版权所有者信息放到单元的最后。例如，读者不会想要翻过两三页诸如“版权所有”等对理解程序毫无帮助且（或）不提供任何编程信息的文本。避免使用垂直滚动条或者关闭的文本框或对话框，这些东西只会增加视觉干扰，而且较难保持一致。采用一个配置管理工具来保存单元历史。 
            <B>
            <LI>如何在适当情况下调用成员函数的例子。</B>最简单的确定一段代码如何工作的方法是看一个例子。考虑包含一到两个如何调用成员函数的例子。 
            <B>
            <LI>可用的前提条件和后置条件</B>。 前提条件是指一个成员函数可正确运行的限制条件；后置条件是指一个成员函数执行完以后的属性或声明 
            [<A 
            href="http://www.xiaopu.com/topic.htm#MEY88">MEY88</A>]。前提条件和后置条件以多种方式说明了在编写成员函数过程中所做的假设 
            [<A 
            href="http://www.xiaopu.com/topic.htm#AMB98">AMB98</A>]，精确定义了一个成员函数的应用范围。 
            <B>
            <LI>所有并行事件。</B>对众多程序开发者来说，并行性是一个新而复杂的概念；对有经验的并行性程序开发者来说，并行性也是一个老但却复杂的课题。最终结果是，如果应用了 
            Java 的并行编程特性，那么应在程序中详细地将其注释出来。[<A 
            href="http://www.xiaopu.com/topic.htm#LEA97">LEA97</A>] 
            建议，当一个类既包含了同步也包含了非同步的成员函数时，必须注释出成员函数依赖的执行上下文，尤其是当函数可被无约束访问时。这样可以让其他开发者安全地使用你的成员函数。当一个采用了 
            <B>Runnable</B> 接口的类的设置函数（即可更新一个字段的成员函数）没有同步时，应说明这样做的理由。 
            最后，如果覆盖或重载一个成员函数，并且修改了它的同步性时，也应说明理由。</FONT> </LI></OL><SMALL>
          <P><FONT 
          size=3><STRONG>仅当注释增加代码的清晰度时，才应加上注释</STRONG>。对于每个成员函数，并非要说明以上所有部分，因为对于每一个成员函数来说，并不是以上所有的部分都适用。但是，对于所写的每个成员函数要说明以上的部分内容。</P></FONT></BLOCKQUOTE></BLOCKQUOTE>
      <BLOCKQUOTE>
        <H3><FONT face=Arial>内部注释</FONT><SMALL> </SMALL><A 
        href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
        height=20 src="" width=26></A></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE>
          <P><FONT size=3>除成员函数注释以外，在成员函数内部还需加上注释语句来说明你的工作。 
          目的是使成员函数更易理解、维护和增强。</P>
          <P>内部注释应采用两种方式：C 语言风格的注释 (/* 和 */) 和单行注释 
          (//)。正如上述所讨论的，应认真考虑给代码的业务逻辑采用一种风格的注释，给要注释掉的无用代码采用另外一种风格的注释。建议对业务逻辑采用单行注释，因为它可用于整行注释和行末注释。采用 
          C 语言风格的注释语句去掉无用的代码，因为这样仅用一个语句就可以容易地去掉几行代码。此外，因为 C 
          语言风格的注释语句很象文档注释符。它们之间的用法易混淆，这样会使代码的可理解性降低。所以，应尽量减少使用它们。</P>
          <P>在函数内，一定要说明： 
          <OL><B>
            <LI>控制结构。</B>说明每个控制结构，例如比较语句和循环。你无须读完整个控制结构内的代码才判断它的功能，而仅需看看紧靠它之前的一到两行注释即可。 
            <B>
            <LI>代码做了些什么以及为什么这样做。</B>通常你常能看懂一段代码做了什么，但对于那些不明显的代码，你很少能判断出它为什么要那样做。例如，看完一行代码，你很容易地就可以断定它是在定单总额上打了 
            5% 
            的折扣。这很容易。不容易的是为什么要打这个折扣。显然，肯定有一条商业法则说应打折扣，那么在代码中至少应该提到那条商业法则，这样才能使其他开发者理解你的代码为什么会是这样。 
            <B>
            <LI>局部变量。</B>虽然我们在第 4 
            章将仔细讨论这一点，在一个成员函数内定义的每一个局部变量都应在它代码的所在行声明，并且应采用一个行内注释说明它的用法。 <B>
            <LI>难或复杂的代码。</B>若发现不能或者没有时间重写代码，那么应将成员函数中的复杂代码详细地注释出来。一般性的经验法则是，如果代码并非显而易见的，则应说明。 
            <B>
            <LI>处理顺序。</B>如果代码中有的语句必须在一个特定的顺序下执行，则应保证将这一点注释出来 [<A 
            href="http://www.xiaopu.com/topic.htm#AMB98">AMB98</A>]。没有比下面更糟糕的事了：你对一段代码做一点简单的改动，却发现它不工作，于是花了几个小时查找问题，最后发现原来是搞错了代码的执行顺序。</FONT> 
            </LI></OL>
          <P><FONT 
          size=3><B>在闭括号后加上注释。</B>常常会发现你的控制结构内套了一个控制结构，而在这个控制结构内还套了一个控制结构。虽然应该尽量避免写出这样的代码，但有时你发现最好还是要这样写。问题是闭括号 
          } 
          应该属于哪一个控制结构这一点就变得混淆了。一个好消息是，有一些编辑器支持一种特性：当选用了一个开括号后，它会自动地使相应得闭括号高亮显示；一个坏消息是，并非所有的编辑器都支持这种属性。我发现通过将类似 
          <B>//end if</B>，<B>//end for</B>，<B>//end 
          switch</B>，&amp;这样的注释加在闭括号所在行的行后，可以使代码更易理解。</P></FONT></BLOCKQUOTE></BLOCKQUOTE><FONT 
      face=Arial><I><B>
      <H2><A 
      name="Techniques for Writing Clean Code">编写清晰整洁的代码的技巧</A></B></I></FONT><SMALL> 
      </SMALL><A href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 
      border=0 height=20 src="" width=26></A></H2>
      <BLOCKQUOTE>
        <P><FONT size=3>这一部分讲述几个技巧，这些技巧有助于区分专业软件开发者和蹩脚代码编写者。这些技巧是： 
        <UL>
          <LI>给代码加上注释 
          <LI>给代码分段 
          <LI>使用空白 
          <LI>遵循 30 秒条规则 
          <LI>说明消息发送的顺序 
          <LI>写短小单独的命令行</FONT> </LI></UL></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial>
        <H3>给代码加上注释</FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE><FONT size=3>
        <P>记住：如果你的代码不值得注释，那么它就不值得保留 [<A 
        href="http://www.xiaopu.com/topic.htm#NAG95">NAG95</A>]。当正确地使用了本文提到的注释标准和方针，就可以大幅度地提高代码质量。</P></FONT></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial>
        <H3><A name=_Toc386368623></A><A name=_Toc386369022></A>让代码分段/缩进 
        </FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <P><FONT size=3>一种提高代码可读性的方法是给代码分段，换句话说，就是在代码块内让代码缩进。所有在括号 <B>{</B> 和 
        <B>}</B> 之内的代码，构成一个块。基本思想是，块内的代码都应统一地缩进去一个单位。</P>
        <P>Java 的约定似乎是开括号放在块的所有者所在行的后面，闭括号应缩进一级。在 [<A 
        href="http://www.xiaopu.com/topic.htm#LAF97">LAF97</A>] 
        指出的很重要的一点是，你所在的机构应选取一个缩进风格并始终使用这种风格。采用与你的 Java 
        开发环境所生成的代码一样的缩进风格。</FONT></P>
        <P><STRONG><FONT face=Arial><SMALL>在代码中使用空白。</SMALL> 
        </FONT></STRONG><FONT size=3>在 Java 
        代码中加入几个空行，也叫空白，将代码分为一些小的、容易理解的部分，可以使它更加可读。[<A 
        href="http://www.xiaopu.com/topic.htm#VIS96">VIS96</A>] 
        建议采用一个空行来分隔代码的逻辑组，例如控制结构，采用两个空行来分隔成员函数定义。没有空白的代码很难读，很难理解。</FONT></P></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial>
        <H3><A name=_Toc386368628></A><A name=_Toc386369027></A>遵循 30 
        秒条法则</FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <P><FONT size=3>其他的程序员应能在少于 30 
        秒钟的时间内完全理解你的成员函数，理解它做什么，为什么这样做，它是怎样做的。如果他们做不到，说明你的代码太难维护，应加以改进。30 
        秒钟，明明白白。 一个好的经验法则是：如果一个成员函数一个屏幕装不下，那么它就很可能太长了。</P></FONT></BLOCKQUOTE>
      <BLOCKQUOTE>
        <H3><FONT face=Arial>写短小单独的命令行</FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <P><FONT 
        size=3>每一行代码只做一件事情。在依赖于穿孔卡片的计算机发展的早期，想让一行代码完成尽量多的功能的想法是可以理解的。若想在一行里做多件事情，就会使代码难于理解。为什么要这样呢？我们应使代码尽量容易理解，从而更容易维护和改进。正如同一个成员函数应该并且只能做一件事一样，一行代码也只应做一件事情。</P>
        <P>此外，应让代码在一个屏幕内可见 [<A 
        href="http://www.xiaopu.com/topic.htm#VIS96">VIS96</A>]。 
        也不应向右滚动编辑窗口来读取一整行代码，包括含有行内注释语句的代码。</FONT></P></BLOCKQUOTE>