角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

II. 选题
项目选题是竞赛取胜的第一步，你可以在这里找到所有开放的程序开发竞赛。该页面中，
你可以看到哪些项目是开放的及其注册、提交的截止日期。这些日期非常重要，你必须在注
册截止日期前确定你对哪个组件感兴趣，并在提交截止日期前提交你的作品，包括测试文件
和文档。难度等级越高，项目难度越大。当然，在这方面个人感觉更为重要。

项目细节
点击项目名称，你将看到该项目的有关细节。包括对于项目具体的描述，项目文档的链
接、报酬信息和一个更为详尽的日期安排。

决定是否参加某项目
找到感兴趣的项目后，请先熟悉一下这个项目的设计文档。最简明的文档就是需求说明
书（Requirements Specification），它包含这个项目会用到的各种技术的信息（如SSL，LDAP，
ODBC 等）。如果你依然兴趣不减，可以继续阅读组件说明书（ Component Specification），
它包含了实现这个组件的更多细节信息。当然，还有其它一些文档，但是这两个文档对决定
一个项目是否适合你是最重要的。
选择一个项目之前，请确保你有足够的时间完成它。项目期间，你是否有其他的安排和
工作要做？另外，项目可能会用到一些你并不熟悉的技术。你知道在C＃中怎样使用数据库
连接吗？你知道怎样使用java.lang.ref 类库吗？你充分了解完成这个组件所需要的网络协议
吗？最好重新阅读一下组件说明书的1.2、1.3 节和第二节，确保你对所用到的技术比较了解。

项目注册
现在，你发现你可以胜任并有时间去完成某个项目，就可以注册了。点击项目细节页面
的注册链接进行注册。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

III. 项目启动－环境
完成注册后，你将有权限访问项目提交程序，并且可以参加组件的开发人员论坛。
项目提交和评审（ Project Submit and Review）
项目提交和评审是你参加程序设计和开发竞赛的核心枢纽。通过这个应用程序，你可以
上传你的作品，查看评审得分。点计进入。登录之后，你将可以看到自己所有开放的项目及
其状态。
点击相应的项目名称可以查看该项目的时间表和其它细节信息。在页面底部，有一排对
应项目当前状态的按钮。另外，还有一个“Contact Product Manager”按钮，你可以随时点
击该按钮向项目经理（Project Manager，PM）发送问题、评论、投诉以及其他信息。
开发者论坛
项目细节页面上有一个指向其开发论坛的链接。绝大部分关于项目的交流、讨论将在此
处进行。你可以使用你的TopCoder 账户、密码登陆所参与项目的论坛。如果不能登录，请
及时与项目经理联系。

开发包
开发人员论坛主要包括四部分：设计阶段文档（Design Phase Documents）、设计阶段问
题（Design Phase Questions）、开发阶段文档（Development Phase Documents）和开发阶段问
题（Development Phase Questions）。你可以在开发阶段文档下找到开发包。开发包中包含所
有与项目开发相关的文档和文件。
通常,Java 开发包是jar 文件，.NET 开发包则是zip 文件，它们都可以用普通的解压工
具解压。
目录
/conf 此目录包含组件的配置文件，有时还会包含所依赖组件的配置文件，或组件设计
者写好的配置文件的例子。如果在设计阶段没有创建这些文件，开发包里面将没有这个目录。
如果你的组件用到了配置文件，你得自己生成这个目录。
/docs 此目录包含组件当前的所有文档。包括.zargo 或.zuml 格式的UML 设计说明，需
求说明书和组件说明书。有关设计文档地更详细信息将在第IV 节中介绍。
/lib 在这个目录下，你可以找到组件依赖的所有组件级别的库文件，不包括系统级别的
库文件（如ODBC 驱动,其他需要复杂安装过程才可以获得的库文件等）。项目依赖的所有
TCS 组件也在这个目录下。如果缺失，你需要和项目经理联系。
/src 当你完成这个项目的时候，此目录应该包含了所有源文件。开发包通常只包含一个
目录框架。开发者负责填充源文件，这将在第IV 节中详细介绍。
/test_files 此目录包括组件测试过程中用到的全部文件。包括测试所需的特殊配置文件、
输入/输出样例、数据库方案和其它任何非编译文件。开发包中一般会包含设计者创建的样
本测试数据。
Java
/METAINF这个目录由jar 打包程序生成，可以忽略。
/build.xml 这是一个缺省的，可能未加配置的构建脚本。构建脚本将在第III 节中详细介绍。
C#
/default.build
这是一个缺省的，可能未加配置的构建脚本。构建脚本将在第III 节中详细介绍。
搭建环境
首先，你需要设置一个工作目录。例如C:/working/、C:/proj/、~/projects/；任何你觉
得合适的地方。建议为TopCoder 项目建立一个新的目录，防止混乱，避免提交一些错误的
文件。在这里，我们假定工作目录为/proj/tc/。
确定了工程放置的目录，就可以解压开发包了。目录/proj/tc/projectname
将是你的工程
目录。这里，我们假定工程名字为tutorial_gen。
下一步是配置构建脚本。记住TCS 不会使用你的构建脚本，不要在它上面花太多时间。
按照下述说明修改路径和库文件引用即可。如果遇到很棘手的问题，你可以向项目经理核实。
Java 构建脚本build.
xml
工程缺省的构建脚本已经基本上可用了。你要做的就是修改JRE1.3 的路径，这在上面
所需软件一节已经提到过。在构建脚本中找到java_1_3_bootclasspath 并进行修改。脚本是
XML 文件，注意不要无意改动了其他内容。
如果你的JRE1.3 的路径是"C:/Program Files/JavaSoft/JRE/1.3.1_10/lib" ， 那么
java_1_3_bootclasspath 需要修改为
value="C:/Program Files/JavaSoft/JRE/1.3.1_10/lib/rt.jar"/>。
大多情况下，这就是你需要做的全部配置工作。如果你不想把JUnit 的jar 包放入
classpath，那么就需要把它加入到构建脚本中。去掉下面的注释，并把${ext_libdir}/junit.jar
修改成正确的路径。

Party Dependencies >
property name="junit.jar" value="${ext_libdir}/junit.jar"/>
>
如果你的工程需要额外的库文件，你需要在构建和运行前通过配置构建脚本来解决这个
问题。在脚本中，应该有些注释掉的库文件的例子。

value="${tcs_libdir}/${spell_check.path}/${spell_check.jar.name}"/>
这样，稍作修改即可对库文件的不同版本进行配置，你可能已经注意到了对${tcs_libdir}
的引用。它应该在脚本文件的开始部分就已经做了如下定义：

配置将在/proj/tc/tutorial_gen/lib/tcs/spell_check/1.0/spell_check.jar 寻找拼写检查的库文件。开发包中可能已经包含了合适的库文件路径；否则，你就需要修改以上路径或文件名属
性。
配置了引用的jar 文件后，你需要把它们加到构建脚本的buildlibs 属性中。

other library references ....>

这里必须包含构建和运行你的组件需要的所有库文件。依赖classpath 是可行的，但是
在buildlibs 中包含需要的库文件才是一个好的习惯。
Java topcoder_
global.properties
或许你已经注意到，开发包中的build.xml 包含对文件"../../topcoder_global.properties"的
引用。通过这个文件，你可以设置一些不随组件而变化的属性，如JRE1.3 的路径。
格式很简单（适用于所有的Java 属性文件）
propertyname=value
首先，在工程目录下创建topcoder_global.properties文件（如果当前工程是/proj/tc/tutorialgen，
你的属性文件将放在/proj/tc 下面）。现在，你可以设置对所有构建脚本的通用属性。
对于JRE，你可以加入：
java_1_3_bootclasspath=C:/Program Files/JavaSoft/JRE/1.3.1_10/lib/rt.jar
你也可以在文件中添加注释。
＃I need a comment to remember what this means.
java_1_3_bootclasspath=C:/Program Files/JavaSoft/JRE/1.3.1_10/lib/rt.jar
你也可以使用扩展属性。
java_home=C:/Program Files/JavaSoft/JRE/1.3.1_10
java_1_3_bootclasspath=${java_home}/lib/rt.jar
需要注意的是，topcoder_global.properties 引用在build.xml 的最起始部分。这意味着
build.xml 中的属性在你的属性文件中不会被扩展（ 还没有定义）。另外，
topcoder_global.properties 中设置的属性会覆盖build.xml 中的属性。想了解更多相关信息，
请参考Ant 文档。

C# 构建脚本default.
build
NAnt 构建脚本和Ant 构建脚本非常相似。
主要需要修改的地方是NUnit 的安装路径。在你的构建脚本中找到如下内容，修改相应
的nunit.framework.dll 路径。

如果你的工程需要额外的库文件，就需要在构建和运行前通过配置构建脚本来解决这些
问题。虽然.NET 中二进制文件的位置更加灵活，但是最好还是直接放在/lib 目录下。

name="generic_parser.dll"/>

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

IV．开发
环境已经搭建好，开发包也解压了，并且配置了构建脚本。接下来要做的一件事就是：
阅读设计文档。
设计文档－你最好的朋友
/doc 目录包含完成提交所需的全部信息。
.zuml /.zargo 在doc 目录下，应该有一份UML 文档。它包含了组件中所有类和接口的
定义。它将定义组件的所有、包括异常行为。
.pdf /.rtf 在doc 目录下，应该有一份组件说明书和需求说明书。组件说明书是UML 文
档的更具可读性的版本。它包含组件常规设计，所需的标准和算法。它非常简明的定义了异
常类和其它所需的信息。你应该用不着需求说明书。它定义了组件的需求，而所有这些需求
应该已经满足。
.gif /.png 这些文档都是由UML 文档生成的，可以不去管它们。其中所有信息都可以通
过UML 文档轻松得到。
开发流程
正如第一节所述，你在开发过程中的角色就是实现已经创建并通过审查的设计。你应该
严格遵循设计文档中给出的公共API。未经项目经理和/或设计者许可，你不得擅自修改组
件的公共API：包括增加或删除public 类、方法和接口。
这并不是说设计会毫无瑕疵；恰恰相反，所有的设计都有改进的空间。然而，对设计的
不同意见要在设计中修正，而不是开发。在开发实行的过程修正设计方案是不合适的，除非
其存在致命缺陷。TopCoder 会对设计的任何改动进行细致审核。

如果你对下个修订版有任何的改进意见和见解，请在论坛上指出。开发过程中遇到的问
题也请立即在论坛上提出来。设计上的任何冲突和问题越早明确，就能越早解决。如果可能，
可以阅读一下设计论坛中的相关讨论，可能这个问题已经提出并被解决了。再强调一次，如
果你发现任何没有解决的问题，请在论坛上提出来！
上面所说的一切，都是为了鼓励你们尽可能的做出改进。如果你能把public 类的行为分
解成私有辅助类，那就去做！如果你能提出一个更加有效的算法，这太棒了！设计中你不能
改变的只有公共API 及从用户角度来说组件的行为。对于一个组件，一般来说，你不可以
改变“是什么”，但是有一定程度上改进“怎样做”的自由。

创新
不同的设计允许不同程度的开发创新。其一方面是设计本身复杂度的原因，另一方面是
设计者的方法问题。或许有的设计方案对组件描述的如此彻底，以至于组件编码变成了将组
件说明书中的伪码翻译成合适的程序设计语言。或许有的设计方案仅仅给出了公共API 的
定义，而将实现细节留给了开发人员。大多数设计方案则是介于这两者之间。
方法体的具体实现一直是程序开发者表现他们手腕的地方。对某些设计方案，添加
private 或packageprivate
的方法、构造函数，甚至设计文档中没有明确说明的类都是可行的，
甚至是必要的。如果你真要这么做，请确保这些改动是必要而且适当的，因为这些地方可能
会引起评审团额外的注意。开发人员所添加的内容（和组件中的其他元素一样）应有最小作
用域，并且予以与其用途一致的最严格的访问控制权限。对于一个任务，确保采用最恰当的
对象或者基本数据类型。
生成站位程序（Stubs）
具体开发的第一步是生成站位程序。站位程序是可编译的代码框架。其中你可以找到函
数体；然而，这仅仅是一个站位程序。这些站位程序刻画了组件的全部API，但并没有实现
其内部逻辑。Poseidon 社区版可以生成Java 站位程序。更贵一些的Poseidon 也可以生成C#
代码。如果没有这些版本的软件，你就需要手工转换这些文件。当然，你也可以从项目经理
那里索要这些站位程序。
你获得的这些站位程序很可能无法成功编译，需要你对它们稍加整理。
站位程序的另一个问题是关联部分。UML 文档里面的一些关系（例如聚合、组合）可
能会被不适当的转化成了代码。程序开发人员负责维护API 文档（UML 文档和组件说明书）
和可编译代码的一致性。

工程结构
工程的源代码应该放在/src 目录下。你的工程应具以下结构（ 所给示例是在
/proj/tc/tutorial_gen/目录下）：
路径描述
conf/ 包含组件必需的配置文件。
docs/ 包含工程的所有文档。
lib/ 包含所有本地库文件。
src/ 所有的源代码都放在此目录下（包括测试代码）。
Java
组件代码放在/src/java/main/目录下。你需要根据包名来组织你的源代码。例如，如果组
件是com.topcoder.util.tutorial ， 那么源代码路径应该是
/src/java/main/com/topcoder/util/tutorial/。下面是典型的Java 的路径：
C#
组件代码放在/src/csharp/main/目录下。你需要根据包名来组织你的源代码。例如，你的
组件是TopCoder.Util.Tutorial.dll ， 你的源代码路径就是
/src/csharp/main/TopCoder/Util/Tutorial/。下面是典型C#路径。尽管C＃的namespace 不要求
目录和包名完全一致，但是根据namespace 来安排的源文件是TopCoder 的惯例。
构建你的工程
生成并整理好站位程序后，你应该可以通过构建脚本来构建你的组件了。你只需从命令
行里运行构建工具即可。
以下是[N]Ant 的常用构建目标：
路径描述
test_files/ 所有测试中用到的不可编译文件。

Java
组件代码放在/src/java/main/目录下。你需要根据包名来组织你的源代码。例如，如果组
件是com.topcoder.util.tutorial ， 那么源代码路径应该是
/src/java/main/com/topcoder/util/tutorial/。下面是典型的Java 的路径：

路径描述
lib/tcs/spell_check/1.0/spell_check.jar 这是一个Tutorial Generator 所依靠的组件的例子。你
的组件可能不依赖于任一组件，也可能依赖于很多
组件。
src/java/main/ 组件代码放在此目录下。
src/java/main/com/topcoder/util/tutorial/ 这是一个站位程序目录的例子。在你的工程里，这
个路径会有所不同。

C#
组件代码放在/src/csharp/main/目录下。你需要根据包名来组织你的源代码。例如，你的
组件是TopCoder.Util.Tutorial.dll ， 你的源代码路径就是
/src/csharp/main/TopCoder/Util/Tutorial/。下面是典型C#路径。尽管C＃的namespace 不要求
目录和包名完全一致，但是根据namespace 来安排的源文件是TopCoder 的惯例。

路径描述
lib/TopCoder.Util.SpellCheck.dll 这是一个Tutorial Generator 所依靠的组件的例子。你
的组件可能不依赖于任一组件，也可能依赖于很多组
件。
src/csharp/main/ 组件代码放在此目录下。
src/csharp/main/TopCoder/Util/Tutorial/ 这是一个站位程序目录的例子。在你的工程里，这个
路径会有所不同。

构建你的工程
生成并整理好站位程序后，你应该可以通过构建脚本来构建你的组件了。你只需从命令
行里运行构建工具即可。
以下是[N]Ant 的常用构建目标：

目标名描述
compile 把工程编译成功能完全的二进制单元（假设你的代码是正确的）。
compile_tests 编译测试代码，依赖于compile 的成功执行。
要执行构建目标，你只需到切换到构建脚本所在的目录（应该是工程的根目录），并执
行ant 或nant 。确保你已经配置好[N]Ant，否则，这一步将失败。
NAnt 的构建示例
Ant 的构建示例
你的组件站位程序应该总能完全干净的构建。如果它们不能成功编译，可能是API 的
问题，也可能是库文件的配置问题。在编写代码和测试前就修正这些问题会简单的多，如果
可能，你也应该这样。
可以休息一会了
到这里，你已经为工程的具体开发做好了准备。有关程序开发技术和策略方面的具体问
题已经超出了这份文档的范畴。在接下来的几节中，我们将介绍有关文档、单元测试和开发
过程中的一些常见问题。
V．文档
文档对一个组件的可用性，可维护性至关重要。如果在写的同时就对代码添加文档，你
或许根本就不会感觉到写文档的负担。评审团会评估文档质量。并且，文档越好，评审团就
越容易看懂和评估你的作品，得分也就越高。
API 文档
你需要对从UML 文档自动生成的API 文档进行修改，而不是把它当作最终版本。在Java
中，API 是通过Javadoc 来注释的，C#中则是通过XML 文档来注释。所有的类、接口、方
法和变量都必须具备文档。以下是分别是Java 和C#的文档例子。
Java
当键入如下内容，很多Java IDE（如Eclipse，IDEA 等）就可以自动生成API 文档。
目标名描述
compile_targets （仅适用于Java）使用配置的JRE1.3 编译你的组件。通常，你需要进行此
操作才可以通过screening。组件说明书的第二节会指明你是否需要此步骤。
test 执行测试，依赖于compile_tests.的成功执行。结束后，测试结果存放在/log
目录下。
clean 清空/build 目录，删除所有的编译代码和中间文件。
dev_submission 将工程打包，以便通过Project Submit and Review 上传。

要执行构建目标，你只需到切换到构建脚本所在的目录（应该是工程的根目录），并执
行ant 或nant 。确保你已经配置好[N]Ant，否则，这一步将失败。
NAnt 的构建示例
Ant 的构建示例
你的组件站位程序应该总能完全干净的构建。如果它们不能成功编译，可能是API 的
问题，也可能是库文件的配置问题。在编写代码和测试前就修正这些问题会简单的多，如果
可能，你也应该这样。
可以休息一会了
到这里，你已经为工程的具体开发做好了准备。有关程序开发技术和策略方面的具体问
题已经超出了这份文档的范畴。在接下来的几节中，我们将介绍有关文档、单元测试和开发
过程中的一些常见问题。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

V．文档
文档对一个组件的可用性，可维护性至关重要。如果在写的同时就对代码添加文档，你
或许根本就不会感觉到写文档的负担。评审团会评估文档质量。并且，文档越好，评审团就
越容易看懂和评估你的作品，得分也就越高。
API 文档
你需要对从UML 文档自动生成的API 文档进行修改，而不是把它当作最终版本。在Java
中，API 是通过Javadoc 来注释的，C#中则是通过XML 文档来注释。所有的类、接口、方
法和变量都必须具备文档。以下是分别是Java 和C#的文档例子。
Java
当键入如下内容，很多Java IDE（如Eclipse，IDEA 等）就可以自动生成API 文档。
目标名描述
compile_targets （仅适用于Java）使用配置的JRE1.3 编译你的组件。通常，你需要进行此
操作才可以通过screening。组件说明书的第二节会指明你是否需要此步骤。
test 执行测试，依赖于compile_tests.的成功执行。结束后，测试结果存放在/log
目录下。
clean 清空/build 目录，删除所有的编译代码和中间文件。
dev_submission 将工程打包，以便通过Project Submit and Review 上传。
/**
* Saves the file to permanent storage, on the path specified by configuration. The path
* must not begin with a backslash, and must not contain any special characters (see component
* specification). If the filename cannot be used, an exception will be * thrown.

*
* @param filename The filename to save to. May not be null or empty.
* @throws IllegalArgumentException If filename is null.
* @throws IllegalArgumentException If filename is not valid (zero length, invalid characters,
etc).
* @throws IOException If an error is encountered while saving the file.
*/
public void SaveAs(string filename)

有关Javadoc 的更详细信息，请参考
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html。
C#
在写代码的同时，Visual Studio.NET 会自动生成大部分XML 文档，只需在声明前面键
入///即可。

///

/// Saves the file to permanent storage, on the path specified by configuration. The path
/// must not begin with a backslash, and must not contain any special characters (see component
/// specification). If the filename cannot be used, an exception will be thrown.
///

/// The filename to save to. May not be null or empty.
/// If filename is null.
/// If filename is not valid
/// (zero length, invalid characters, etc).
/// Ifan error is encountered while saving the file.
public override void SaveAs(string filename)

虽然C#中不会对throws 语句进行检查，但是在API 文档中注明该方法可能产生的异常
是个好习惯。有关XML 文档的更详细信息，请参考
http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/default.aspx。
文档的内容
解释组件的行为，非法输入及相应的异常行为。明确对象因为某种操作而发生的变化（对
List.add(object)而言，这可能显而易见；而对List.screenedAccept(object,bool)来说，可能就不
是那么明显了）。务必注明方法的返回值，可能抛出的异常和所有的参数。此外，每个类和
接口都需要有个概括性文档，以解释其作用。
请不要在组件中包含任何个人标识信息。任何需要用到你的TopCoder 账号(handle)的地
方（例如@author 标签），请用TCSDEVELOPER代替，保证客观、公平。组件的获胜者
将会在修正（Final Fix）阶段将handle 写入自己的组件。

文档的读者
API 文档的读者将是组件的使用者：TopCoder 软件的客户。在文档中请保持专业口吻；
使用主动语态；语言尽量具有描述性，要考虑到组件的使用者可能没有你对语言和组件这么
熟悉。
前面已经说过，从UML 直接产生的文档不是合适的最终版本。例如：SaveAs 函数可能
会有如下的文档：
这段文字描述了SaveAs 函数的功能；但是，它更多的是为程序开发者自己写的，而不
是其用户。你可能想删除其实现细节，而又清晰、准确的解释函数的行为。“funny character”
可能对内部人员适用，但是对用户来说是不行的。请将这些条目熟记于心，当你完成一个函
数的时候，请重写其API 文档。
内嵌式文档
内嵌式文档是一段代码中解释代码功能的文档。内嵌式文档是为组件使用者以及
TopCoder 改进所用的。和任何其他程序设计过程一样，你注释得越详细，代码就越容易维
护。x++，一个简单的自增语句，没有必要注释。但是loopIndex++， recordCount++可能更
合适。如果一段代码的意图不甚明显的话，你可能就需要添加一些注释了。
必备文档
关于API 文档和内嵌文档并没有硬性规定，对它们的评审将会比较主观。
然而，以下几项是基本要求：
 每个文件必须包含TopCoder 版权声明。
 所有的public API 元素必须有详细的文档注释（参数，返回值，异常），注意：包
括单元测试。
 任何复杂或比较大的程序段必须包含内嵌式文档以解释其目的和功能。
 文档必须具备专业的口吻和质量。
将这些指导原则牢记于心，你可以在文档方面得到高分了。
VI．单元测试
组件无论大小都需测试。测试的目的是保证组件对各种输入均有正确的行为。我们的单
元测试风格起源于极限编程。你不一定要以这种风格来编程，需要获取有关极限编程和单元
Pull the path info from the config file, then append the filename passed in. Attempts
to save the file to that location, throws exception otherwise.
Invalid Input: null, blank, funny characters, nonfs
safe
Valid Input: everything else
Throws: IOException on failure, InvalidArgumentException if it is

这段文字描述了SaveAs 函数的功能；但是，它更多的是为程序开发者自己写的，而不
是其用户。你可能想删除其实现细节，而又清晰、准确的解释函数的行为。“funny character”
可能对内部人员适用，但是对用户来说是不行的。请将这些条目熟记于心，当你完成一个函
数的时候，请重写其API 文档。
内嵌式文档
内嵌式文档是一段代码中解释代码功能的文档。内嵌式文档是为组件使用者以及
TopCoder 改进所用的。和任何其他程序设计过程一样，你注释得越详细，代码就越容易维
护。x++，一个简单的自增语句，没有必要注释。但是loopIndex++， recordCount++可能更
合适。如果一段代码的意图不甚明显的话，你可能就需要添加一些注释了。
必备文档
关于API 文档和内嵌文档并没有硬性规定，对它们的评审将会比较主观。
然而，以下几项是基本要求：
 每个文件必须包含TopCoder 版权声明。
 所有的public API 元素必须有详细的文档注释（参数，返回值，异常），注意：包
括单元测试。
 任何复杂或比较大的程序段必须包含内嵌式文档以解释其目的和功能。
 文档必须具备专业的口吻和质量。
将这些指导原则牢记于心，你可以在文档方面得到高分了。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

VI．单元测试
组件无论大小都需测试。测试的目的是保证组件对各种输入均有正确的行为。我们的单
元测试风格起源于极限编程。你不一定要以这种风格来编程，需要获取有关极限编程和单元
Pull the path info from the config file, then append the filename passed in. Attempts
to save the file to that location, throws exception otherwise.
Invalid Input: null, blank, funny characters, nonfs
safe
Valid Input: everything else
Throws: IOException on failure, InvalidArgumentException if it is
测试方法论的更详尽的信息， 请参考http://www.xprogramming.com 或者
http://junit.sourceforge.net/#Documentation。
在极限编程中，测试先行。当然，这不是必须的，但非常有效。程序API 很大程度上
是不变的, 这使得对照其写测试用例成为可能，而不需要管是否能通过。随着你的开发进度，
不断测试，你的组件将会通过越来越多的测试。

什么是单元测试
单元测试是程序功能模块最细微的测试（测试功能的每个单元）。通常，这意味着需要
单独测试所有非private 的方法和构造函数。单元测试既需要验证程序在合法状态和输入下
的行为（包括极限情况），也需要验证其在所有可测的出错情形下的异常行为。
测试范围
单元测试的范围可以尽可能的广。有时，单元测试的代码量甚至会超过被测试的代码量。
组件的所有public 函数都必须有相应的测试：包括准确性测试和异常测试（对应合法和
非法的输入）。测试面越广，组件的bugs 就越容易暴露。要想覆盖所有的输入情形是非常困
难的（有时甚至是不可能的）。但是，输入覆盖面越大，组件就越可靠。
除了这些小的、原子性测试，你也应该创建测试来查看你的组件是否始终提供了所期望
的功能。
创建你的单元测试
第一步是在src 文件夹下创建单元测试的目录。每种语言因测试目的而有细微不同。
创建C#单元测试
创建Java 单元测试

单元测试技巧
将所有的单元测试放在一个函数中听起来非常有诱惑力。但是，这样会极大地降低测试
的效果。在上面的例子中，我们可以简单的将三个测试函数组合成一个：testSaveAs（）。现
在我们只有一个测试函数，而不是三个。如果三个当中任何一个失败的话，整个测试将失败。
在大规模测试中，这种组合测试的方法论将会导致失败条件的混乱，测试的调试将变得困难。
测试用例越小，功能越单一，错误点和可能的原因就越明显。
 总是实现组件说明书中的demo。
 总是在assert 和fail 调用中提供有意义的信息
 总是像注释组件代码一样注释测试用例
 把测试用例组织成TestCase 类, 如果一个TestCase 已经难于管理, 请拆成两个或者
更多的类
 将TestCase 类中的测试用例拆分成尽可能小的功能集；这样，组件的哪部分出现
了问题就一目了然。你也可以用测试用例通过和失败的情况作为组件完成与否的标
准。

 通过setUp（）和tearDown（）来减少重复代码，增加可靠性。
 时间允许的情况下，用尽可能多的合法，非法输入对每个public 函数进行测试
 测试组件期望的流程。比如：载入数据、处理数据、保存数据。
 不要忘记清空测试环境。单元测试后，系统应保持在测试前的状态，而不是产生了
持久的影响。此问题将会在评审过程中进行检查。
 除了对测试框架的特殊意义，测试类在各方面都是正常的类。这些类可以继承介于
它们自己和最终测试间的类，可以包含非测试用的方法，并且有状态。
 因为它们和被测试的组件类处于同一包或namespace 下，单元测试可以访问具备包
访问属性或者protected 访问属性的类及其成员。
 接口不能直接测试，但是可能存在以接口为参数的方法。这种技术使得验证组件是
否对于接口类型的域和参数有正确的行为以及组件是否正确处理了此类方法调用
时的抛出的异常潜力巨大。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

VII．问题
在开发过程中，你可能会遇到一些问题。或许你需要额外的组件，或许组件本身设计的
有瑕疵导致开发无法进行。你或许对设计者的意图感到疑惑，或许对组件使用的技术感到不
解。别担心，你并不孤单。
如果发现设计有任何不明确的地方，你都可以在组件论坛中进行提问（从Project Submit
& Review 进入）。你可能会遇到一些设计者没有考虑到的情况。你可能错读了组件，或者
没有注意到一些事项。任何情况下，组件本身相关的问题都应该在组件论坛中说明。
另一方面，如果你在写代码过程中遇到了困难，或对某种技术不甚了解，或者遇到了某
种程序bug，你可能就需要去TopCoder 自由讨论区(Round Tables)了，而不是开发论坛。自
由讨论区的URL 是 http://www.topcoder.com/rtables/index.jsp。其中一般讨论区或组件竞赛讨
论区是寻求帮助的合适地点。自由讨论区是一些经验丰富的TopCoder 成员和TopCoder 软件
职员经常光顾的地方。他们都会提供最大的帮助。
如果你遇到一些问题，使你不能继续你的组件，请立即给项目经理发Email。这些问题
包括文件缺失或者错误，访问或者应用程序问题，重大的设计问题等。你可以通过组件的
Project Submit & Review Details 页面给项目经理发Email。如果你不能访问上述页面，你可
以直接发邮件至 service@topcoder.com， 说明你所注册的组件和遇到的问题。
readme 文件不是一个好的交互方法。如果需要对组件做任何大的改动，你必须与组件
设计者和项目经理联系。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

VIII．提交
艰苦的工作已经结束，此时你的组件已经通过了所有150 个测试。可以准备提交了。
首先，你需要检查你的代码，确保尽可能符合评审条款（第IV 节）。一些细枝末节的问
题也会在稍后的评审过程中降低你的分数。确保你的目录结构符合要求。
其次，确保你的代码成功编译，如果你做的Java 组件，确保compile_targets 命令成功
编译了组件。
最后，执行dev_submission，生成文件的压缩归档。务必检查一下你写的所有文件是否
全部包含其中，需要的话加入缺失的文件。你的提交需要包含单元测试成功执行的日志文件，
conf/目录下的所有文件，test_files/目录下的文件及目录。如果有时间的话，你可以将归档文
件解压到另外一个目录下重新构建以确保成功。
如果你对自己将要提交的归档文件已经比较满意了，就可以通过Project Submit &
Review 上传！
使你的提交出类拔萃
想要在开发竞赛中胜出，你必须使你的提交出类拔萃。
对于简单、比较具体的组件来说，这是一个诀窍；即使对于较复杂、抽象一些的组件来
说，也应当给与足够的重视。有多种方法让你提交的作品脱颖而出，这里给出几点建议：
 写简洁、清晰而高效的代码。虽然这方面没有明确的评审条目，不过评审员总是喜
欢那些对他们来说易读易懂的代码。高效的代码可以使你的程序在压力测试和基准
测试中表现优异，从而得到一些额外的分数。
 单元测试务必全面。你可能会为测试不足付出高昂的代价，因为在评审条目中有好
几条是关于单元测试的。单元测试应该覆盖所有非私有方法，并且需要良好的文档
注释。在测试方面的良好表现会是赢得组件的重要砝码，因为单元测试是很容易被
忽略的部分。
 提供卓越的文档注释。类和方法的文档是由开发人员负责，但是似乎很少有人给它
应有的重视。良好的文档必须清晰，容易理解。了解并熟悉Javadoc 的文档。例如：
任何HTML 标签都可以插到文档注释中，适当的应用这种特性将会非常有效。试
着站在别的程序开发人员的角度问自己：你想要知道组件的什么信息，然后将其写
下来。了解并遵循Sun 或Microsoft 的文档注释指南，以及相关如何写API 规范的
文档。
 完全符合要求，提供所有要求的功能。或许，这是理所当然的；但是任何差错都会
减少你获胜的机会。小心特殊情况和非正常输入。
 注意任何设计者忽视的问题。比如：线程安全，可移植性（即使是Java 或者.NET
也存在移植性问题）。请在设计框架内仔细斟酌，使你的提交具备想要的特性。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

IX. 评审
评审团将根据以下要点对你提交的作品进行评判。你可以查看详细的分数卡信息。
程序提供了组件设计文档所述的全部功能。组件是不是提供了设计所规定的功能？它是
不是按照要求的方式完成？
程序正确的地运用了组件所要求的技术。你的组件适当运用了所有相关的技术吗？你有
没有合理的连接数据库？有没有合理的运用XML 配置？此条款也适用于设计元素如
singleton 设计模式和同步问题。
程序合理实现了组件说明书1.3 节所要求的算法。如果你的组件里有比较复杂的算法，
它们可能已经在设计中指明。如果你对算法做了改进，此栏你可以获得额外的分数。如果发
现1.3 节中的说明有什么问题，把它发到论坛上来，和设计者一起寻求解决办法。作为程序
开发人员，你应当对组件的行为负责，即使算法设计存在缺点。
所有类、方法以及变量的声明都和设计文档中的定义完全一致（可视性、类型、修饰词、
名字和异常）。你必须严格遵循设计的API。除非征得设计者或PM 的同意，不得删除、添
加或者修改任何公共API。
不得在设计中添加额外的public 或protected 实体。你只能在组件中添加private 实体。

包访问特性或者protected 的变量是不允许的。只要合适的融入design 中，包访问特性的方
法是允许的。如果只是用来提供辅助方法，包访问特性的类是允许的。private 变量、方法和
内部类都是允许的。所添加的实体必须遵循语言的命名规范，并且措辞得体。注意，当有多
个包时，辅助类可能需要是public 的。在这种情况下，关于添加公共类和方法的限制可以放
松。
程序实现合理的反映了类间关系。如果你按照设计要求来实现，这点通常已经满足。除
非确有必要，你不可以在类之间增加依赖或者关联。
程序中对象类型定义是最好的选择。作为程序开发人员，你必须在不同对象类型间做出
选择。比如：你可能决定用一个TreeMap 去存储一些键值对。然而，除非你需要保持键的
相对顺序，你应该使用HashMap 。在这里，“最好的选择”通常是与效率相关。
没有无用的代码。不要写臃肿的编码。C#和Java 库都可以复制数组，都可以将容器转
换成换成数组。不要重新实现标准库已经实现的功能。不要赋值给不用的变量。不要在组件
中遗留测试或者临时函数。
没有编码冗余。尽可能将代码分解成辅助函数和辅助类。运用重载减少重复代码。当然，
不要太极端。尽可能减少重复，而又不要写成50 个仅一行的函数。你要做出权衡。
代码简洁、高效。这项有些主观，但是也有客观参照。你一般不应该对三元选择运算符
进行套嵌(如good ? "great!" : ok ? "I suppose" : bad ? or_is_it ? "darn" : "phew" : "who
knows?" )。这非常不清晰。与此类似，大段的代码……如果某个函数超过了50 行，你可能
需要把它分解成多个函数。例如：如果你正在画一个图，你可以有一个drawAxes()函数，一
个drawData()函数，还有一个drawLegend()函数，而不是一个非常大的代码块。效率方面，
很小的改进也可以产生明显的效果。当你已经达到期望值的时候，从查找中跳出。智能设置
控制条件，运用短路求值法。不要把你的代码写的过于复杂，能简化的尽量简化。
抛出的异常提供了合适的错误信息和原因。和文档一样，异常应该简洁、详细、专业。
“IT SCREWED UP AGAIN”不是一个合适的异常信息，无论当时感觉多么合适。
所有代码，包括测试用例，都遵循TopCoder 编码规范。我们的编码规范是已发布的Java
和C#标准。你可以通过以下链接查看：
Java 编码规范
.NET 编码规范
程序实现包含关于类、方法和变量的文档，并以Java / C#编码标准所要求的Javadoc /
XML 风格编写。参考文档一节可以获取更多信息。文档应该详细、全面而专业。语法和拼
写错误也是我们的评价要素。
在产生Javadoc/XML 文档的时候没有错误和警告。文档必语法正确：没有不存在的元
素的文档，没有畸形的文档元素。
单元测试正确、彻底地测试了所有的方法和构造函数。单元测试非常重要，你必须彻底
的测试你的组件。参考单元测试一节。
单元测试包含一个演示组件如何使用的Demo。你应该模拟并演示如何使用组件；你应
该实现组件说明书关于的如何使用组件的例子。
单元测试合理配置了测试环境。请使用配置文件和setUp()、tearDown()，以得到高分。
在单元测试中用到的文件位于test_files 目录下。如果你的单元测试需要一些额外的文
件才得以执行，请将它们放在这里；否则，你将会被扣分。
单元测试完成后，没有在文件系统中残留临时文件，没有打开的网络或数据库连接，没
有打开的文件或流。测试可能会被TCS 或者客户频繁的运行。测试完毕后系统应该和测试
前处于同一状态，没有留下残骸。
单元测试包含详细的类、方法和变量的文档。像注释组件代码一样注释单元测试。
此外，三个程序开发评审员的都会写单元测试程序，以探察你的组件在精确性、适当的
异常行为以及压力测试下的表现。基于以上这些要点以及测试结果，你的组件将会得到一个
分数。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

X．申诉
评审结束后，你将有几天时间查看你的组件得分并进行申诉。你将看到分数卡上关于以
上每一条的评论，而且可以为分数进行争辩。需要注意的是，你的申诉必须理由充分，否则
将会被拒绝。如果评审员的陈述与设计相冲突，或者评审出现了差错，不要顾忌，申诉！另
外，观念性的问题一般不要申诉。如过你是组件的获胜者，在修正阶段你将有机会讨论评审
员的评判。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

［Ryan.Bay 于 2008-4-15 18:13:46 编辑过］

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

XII. 提交和终审
这仅仅是一次dev_submission 的构建过程。遵循同样的指导原则，保证上传了所有文件。
使你的提交尽可能完善。这样将节省所有人的时间，包括你自己。
如果你的提交已经满足了所有要求，通过了所有评审的测试，组件也就完成了，并将添
加到目录中。你的工作也就完成了。

角　　色：注册用户
发 帖 数：431
经 验 值：762
注册时间：2008-3-19

联系
收藏

编辑
删除

XIII. 结论
再次祝贺你！经过注册、开发、测试、提交、被审查、申诉、获胜、修正并再次提交，
你得到了报酬，并且还可以从你所做的工作中得到版税！有什么庆祝方式会比再注册一个新
的项目并且完成它更好呢？