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 元素必须有详细的文档注释（参数，返回值，异常），注意：包
括单元测试。
任何复杂或比较大的程序段必须包含内嵌式文档以解释其目的和功能。
文档必须具备专业的口吻和质量。
将这些指导原则牢记于心，你可以在文档方面得到高分了。
2008-4-15 18:02:06
1199
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
