javaformat.htm

JAVA CODE AND SOME USERFULL CODE

              <TD vAlign=top width="40%"><FONT 
                size=3>在成员函数内部采用单行注释语句对业务逻辑、代码片段和临时变量声明进行说明。</FONT></TD>
              <TD vAlign=top width="40%"><FONT size=3>// 因为让利活动 
                <P>// 从 1995 年 2 月开始，</P>
                <P>// 所以给所有超过 $1000 的</P>
                <P>// 发货单 5% 的折扣。</FONT></P></TD></TR></TBODY></TABLE><FONT size=3>
          <P>一件很重要的事情是，你的机构应该制订一套如何使用 C 
          语言风格注释和单行注释的标准，并始终严格遵守。使用一种注释方式来说明业务逻辑，使用另一种方式注释掉旧的代码。业务逻辑采用单行注释，因为这样可以将注释和代码放在同一行（这又叫做“内联”）。采用 
          C 语言风格的注释屏蔽掉旧的代码，因为这样可以同时注释掉数行。C 
          语言风格注释看起来很象文档注释，所以为了防止混淆，不应在别处使用。</P></FONT>
          <P><B>注意行末注释。</B><FONT size=3>[<A 
          href="http://www.xiaopu.com/topic.htm#MCO93">MCO93</A>] 
          强烈反对采用行内注释，即在一行的末尾加上注释。他指出，这种注释必须在代码的右端对齐，这样才能避免代码结构看起来混乱。结果，这些注释的格式难以划一。“如果你使用了很多这样的注释，则要花时间去将它们排列整齐。这些时间并没有花在更多地了解代码上，而完全花在了敲击空格键和制表符这种冗长乏味的工作上。”他又指出，行末注释也难以维护。因为当该行程序的代码加长时，它们会将这些注释挤出该行，如果你将它们排齐了，你不得不对余下的注释做同样的工作。</FONT></P>
          <H4><A name="A Quick Overview of javadoc"><FONT face=Arial><BIG>快速浏览 
          <EM>javadoc</EM></BIG></FONT></A> <BIG><A 
          href="http://www.xiaopu.com/topic.htm#Top"><IMG alt=返回目录 border=0 
          height=20 src="" width=26></A></BIG></H4></BLOCKQUOTE>
        <BLOCKQUOTE>
          <P><FONT size=3>Sun 公司的 Java Development Kit (JDK) 中有一个名为 
          <I>javadoc</I> 的程序。它可以处理 Java 的源代码文件，并且为 Java 程序产生 HTML 
          文件形式的外部注释文档。Javadoc 支持一定数目的标记，标识注释文档中各段起始位置的保留字。详情请参考 JDK 
          <I>javadoc</I> 文档。</P></FONT>
          <TABLE border=1 cellPadding=7 cellSpacing=1 width=583>
            <TBODY>
            <TR>
              <TD bgColor=#ffffff vAlign=top 
              width="32%"><B><BIG>标记</BIG></B></TD>
              <TD bgColor=#ffffff vAlign=top 
              width="19%"><B><BIG>用于</BIG></B></TD>
              <TD bgColor=#ffffff vAlign=top 
              width="49%"><B><BIG>目的</BIG></B></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@author name</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、 
                <P>接口</FONT></P></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>说明特定某一段程序代码的作者。每一个作者各有一个标记。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@deprecated</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、 
                <P>成员函数</FONT></P></TD>
              <TD vAlign=top width="49%"><FONT size=3>说明该类的应用程序编程接口 (API) 
                已被废弃，因此应不再使用。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@exception name 
                description</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>成员函数</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>说明由成员函数发出的异常。一个异常采用一个标记，并要给出异常的完整类名。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@param name 
                description</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>成员函数</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>用来说明传递给一个成员函数的参数，其中包括参数的类型/类和用法。每个参数各有一个标记。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@return 
                description</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>成员函数</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>若成员函数有返回值，对该返回值进行说明。应说明返回值的类型/类和可能的用途。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@since</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、成员函数</FONT></TD>
              <TD vAlign=top width="49%"><FONT size=3>说明自从有 JDK 1.1 
                以来，该项已存在了多长时间。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@see ClassName</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、接口、成员函数、字段</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>在文档中生成指向特定类的超文本链接。可以并且应该采用完全合法的类名。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@see ClassName#member 
                functionName</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、接口、成员函数、字段</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
                size=3>在文档中生成指向特定成员函数的超文本链接。可以并且应该采用完全合法的类名。</FONT></TD></TR>
            <TR>
              <TD vAlign=top width="32%"><FONT size=3>@version text</FONT></TD>
              <TD vAlign=top width="19%"><FONT size=3>类、接口</FONT></TD>
              <TD vAlign=top width="49%"><FONT 
            size=3>说明特定一段代码的版本信息。</FONT></TD></TR></TBODY></TABLE><FONT size=3>
          <P>你注释代码的方式很大地影响着你的工作效率以及所有维护改进代码的后继开发者的工作效率。在软件开发过程中及早注释代码，会促使你在开始撰写代码之前仔细考虑这些代码，从而带来更高的工作效率。而且，当你重新阅读数天前或者数星期前所写的代码时，你可以很容易地判断出当时你是怎么想的，因为这一切都有记录。</FONT></P></BLOCKQUOTE></BLOCKQUOTE>
      <HR align=left>

      <H1><FONT face=Arial size=6><A 
      name="Standards For Member Functions"><B>成员函数标准</B></A></FONT><SMALL> 
      </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>切记：你今天所写的代码可能在今后的数年里仍在使用，而且很有可能由其他人来维护和改进。应尽可能使你的代码“整洁”易懂，因为这会使代码易于维护和改进。</FONT><FONT 
      face=Arial><I><B></P>
      <H2><SMALL><A 
      name="Naming Member Functions">命名成员函数</A></SMALL></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>成员函数的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。成员函数名称的第一个单词常常采用一个有强烈动作色彩的动词。</FONT></P><B>
        <P class=exampleheading><BIG>示例：</BIG></P></B><FONT size=3>
        <P class=example>openAccount()</P>
        <P class=example>printMailingLabel()</P>
        <P class=example>save()</P>
        <P class=example>delete()</P>
        <P>这种约定常常使人一看到成员函数的名称就能判断它的功能。虽然这种约定要使开发者多做一些输入的工作，因为函数名常常较长，但是回报是提高代码的可理解性。</FONT></P></BLOCKQUOTE><FONT 
      face=Arial>
      <H2><SMALL><A 
      name="Naming Accessor Member Functions"><EM>命名存取成员函数</EM></A></SMALL></FONT><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>在后续章节中，我们将更详细地讨论获取和存放字段值（字段/属性）的存取成员函数。下面将概括一下存取函数的命名约定。</FONT></P></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial><B>
        <H3><A name=Getters><SMALL>获取函数</SMALL></A></B></FONT></H3></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE>
          <P><FONT size=3>获取函数作为一个成员函数，返回一个字段的值。除了布尔字段之外，应采用 get 作为字段的前缀；布尔字段采用 
          is 作为前缀。</FONT></P></BLOCKQUOTE>
        <BLOCKQUOTE><B>
          <P class=exampleheading><BIG>示例：</BIG></B></P></BLOCKQUOTE><FONT size=3>
        <P class=example>getFirstName()</P>
        <P class=example>getAccountNumber()</P>
        <P class=example>isPersistent()</P>
        <P class=example>isAtEnd()</P></FONT>
        <BLOCKQUOTE><FONT size=3>
          <P>遵循这个命名约定，显然，成员函数将返回对象的字段，布尔型的获取函数将返回布尔值“真”或者“假”。这个标准的另一个优点是：它遵循 
          beans development kit (BDK) 对获取成员函数采用的命名约定 [<A 
          href="http://www.xiaopu.com/topic.htm#DES97">DES97</A>]。它的一个主要的缺点是 get 
          是多余的，需要额外的录入工作。</FONT></P></BLOCKQUOTE></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE><FONT face=Arial size=3>
          <H3>获取函数的另一种命名约定。Has 和 Can</FONT></H3></BLOCKQUOTE></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE>
          <P><FONT size=3>基于正规英文约定的一个可行的取代方法是，用 has 或者 can 来代替布尔型获取函数的 is 前缀。 
          例如，形如 <B>hasDependents()</B> 和 <B>canPrint()</B> 
          的获取函数，读起来就发现它们意义更加明确。这种方法存在的问题是 BDK 目前还不支持这种命名方法。可以将 
          <B>isBurdenedWithDependents()</B> 和 <B>isPrintable()</B> 
          这些成员函数重新命名。</P></FONT></BLOCKQUOTE></BLOCKQUOTE>
      <BLOCKQUOTE><FONT face=Arial><B>
        <H3><A name=Setters>设置函数</A></B></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>设置函数，也叫变值函数，是可以修改一个字段值的成员函数，。无论何种字段类型，都要在字段名的前面加上 set 
          前缀。</FONT></P></BLOCKQUOTE>
        <BLOCKQUOTE><B>
          <P class=exampleheading><BIG>示例：</BIG></B></P></BLOCKQUOTE><FONT size=3>
        <P class=example>setFirstName(String aName)</P>
        <P class=example>setAccountNumber(int anAccountNumber)</P>
        <P class=example>setReasonableGoals(Vector newGoals)</P>
        <P class=example>setPersistent(boolean isPersistent)</P>
        <P class=example>setAtEnd(boolean isAtEnd)</P>
        <BLOCKQUOTE>
          <P>按照这种命名约定，显然是一个成员函数设定一个对象的字段值。这个标准的另一个优点是：它遵循 beans development kit 
          (BDK) 对设置函数采用的命名约定 [<A 
          href="http://www.xiaopu.com/topic.htm#DES97">DES97</A>]。 它的一个主要的缺点是 
          set 是多余的，需要额外的录入。</P></BLOCKQUOTE></FONT></BLOCKQUOTE><B>
      <H2><FONT face=Arial><A name=Constructors>命名构造函数</A></FONT></B><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>构造函数是在一个对象初次生成时，完成所有必需的初始化的成员函数。构造函数与它所属类的名字总是相同的。例如，类 
        <B>Customer</B> 的构造函数是 <B>Customer()</B>。注意大小写一致。</FONT></P></BLOCKQUOTE>
      <BLOCKQUOTE><B>
        <P class=exampleheading><BIG>示例：</BIG></B></P></BLOCKQUOTE>
      <BLOCKQUOTE>
        <BLOCKQUOTE><FONT size=3><PRE>Customer()</PRE><PRE>SavingsAccount()</PRE><PRE>PersistenceBroker()</PRE></FONT></BLOCKQUOTE></BLOCKQUOTE>