普林斯顿算法课 评估指南 Assessment Guide

Assessment Guide

​  在您提交代码后，将会自动为您分析程序的风格，正确性，内存使用情况和时间安排。 然后将结果编译成报告，您可以在评分脚本完成后单击提交按钮旁边的分数来查看报告。
​   该报告由两个主要部分组成，即评估总结和评估细节。 评估细节部分进一步细分为编译，API，FindBugs，PMD，Checkstyle，Correctness，内存和Timing.

Asssessment Summary 评估总结

例子如下：

Compilation: PASSED
API:         PASSED
Findbugs:    PASSED
PMD:         FAILED (1 warning)
Checkstyle:  FAILED (0 errors, 3 warnings)
Correctness: 13/14 tests passe
Memory: 0/4 tests passed
Timing: 2/5 tests passed
Raw score: 73.71% [Compilation: 5%, API: 5%, Findbugs: 0%, PMD: 0%, Checkstyle: 0%, Correctness: 65%, Memory: 10%, Timing: 25%]

1. 编译测试检查您的Java程序是否在没有警告或错误的情况下编译。 如果autograder无法成功编译您的程序，您将不会收到任何信用额外的反馈。
2. API测试验证您的类的API与作业要求规定的API完全匹配。 如果有任何不匹配，您将不会收到任何信用或额外的反馈。
3. Findbugs和PMD测试检查您的程序是否有常见的错误模式。 测试结果既不会计入您的分数，也不会阻止额外的分析。
4. Checkstyle测试检查你的程序是否遵循一组样式规则（详见下文）。 结果既不会计入您的分数，也不会阻止额外的分析。
5. Correctness测试程序是否正确
6. Memory测试分析你的程序的内存使用情况
7. Timing测试你的程序运行时间
   各自的权重为：Compilation 5% + API 5% + Correctness 60% + Memory 10% + Timing 20%。上面例子的学生成绩为：5% + 5% + （13/14 * 60%）+ （0/4 * 10%) + (2/5 * 20%) = 73.71%。

Assessment Detail

首先是提交的文件列表，如下所示：
files submitted
———————————-
3.4K Aug 16 00:03 Percolation.java
3.4K Aug 16 00:01 PercolationStats.java
1. Compilation: autograder使用Java 8编译器来编译你的Java程序，但是对某些程序包（如java.net和java.util.concurrent）的访问受到限制。 autograder在classpath中包含了algs4.jar的命名包版本。 它还使用-encoding UTF-8选项，该选项拒绝未使用UTF-8编码的输入文件。 这是一个例子。

******************************************************************************
*  compiling
******************************************************************************
% javac Percolation.java
*-----------------------------------------------------------
================================================================
% javac PercolationStats.java
*-----------------------------------------------------------
PercolationStats.java:3: <identifier> expected
    StdOut.printf("% java PercolationStats ");
                 ^
PercolationStats.java:3: illegal start of type
    StdOut.printf("% java PercolationStats ");
                  ^

程序Percolation.java明显编译，但程序PercolationStats.java不能。 autograder能显示任何编译器错误或警告。 在机器上本地编译时，您应该看到类似的消息。
2. API
API测试确保您的程序符合作业要求的规定（包括类定义，构造函数，实例变量和实例方法）中指定的确切API。 你的程序可能包含其他构造函数，实例变量和实例方法，但是它们必须声明为私有private的。 一个例外是public static void main（String [] args），即使没有指定，也可以随意包含它。 而且，和Java一样，如果在API中没有指定其他的构造函数，autograder就会假设一个默认的无参构造函数。 最后，由于API检查器的技术限制，如果API指定了泛型类型参数的名称，则必须在程序中使用相同的名称。

Testing the APIs of your programs.
*-----------------------------------------------------------
Percolation:
The following fields should be made private:
  *  public WeightedQuickUnionUF gridUF
The following methods should be removed or made private:
  *  public int xyToUF(int,int)
PercolationStats:
The following methods are missing:
  *  public double mean()
================================================================

在上面的例子中，API检查器在Percolation.java中报告两个API违例。 第一个是名为gridUF的公共实例变量; 第二个是名为xyToUF（）的公共实例方法，它们都不出现在作业要求中。 API检查器在PercolationStats.java中报告一个API违例：缺少mean（）方法。 在您纠正所有API违规之前，您的程序将不会被打分。
3. Findbugs
Findbugs扫描Java字节码并寻找常见的错误模式。 autograder使用Findbugs 3.0.1和配置文件findbugs-coursera.xml。 这是一个bug描述列表。 Findbugs偶尔会报告误报，所以autograder不会将结果计入您的分数。

% findbugs *.class
*-----------------------------------------------------------
H B ES_COMPARING_STRINGS_WITH_EQ ES: Compares two strings for reference equality using '==' or '!='. Use the 'equals()' method for object equality (to check whether two strings correspond to the same sequence of characters).  At HorseSorter.java:[line 128]

Warnings generated: 1
================================================================

在上面的例子中，Findbugs报告了一个问题：使用==运算符而不是equals（）方法来比较两个字符串。 通常情况下，这不是你想要的，所以Findbugs将其标记为可疑。
4. PMD

PMD扫描Java源代码并查找常见的错误模式。 autograder使用PMD 5.7.0。 这是一个bug descriptions。 有时，PMD报告误报，所以自编者不会将结果计入您的分数。

% pmd *.java
*-----------------------------------------------------------
PercolationStats.java:112: Avoid unused method parameters such as 'alpha'. [UnusedFormalParameter]
PMD ends with 1 warning.
================================================================

在上面的例子中，PMD报告了一个问题：形式参数alpha从来没有被其方法使用。

1. Checkstyle

Checkstyle扫描Java源代码，并验证代码是否符合一组样式准则。 autograder使用Checkstyle 8.5和配置文件checkstyle-coursera.xml。 这是一个可用的availabel checks列表。 由于风格本质上是主观的，你可能会不同意风格检查。 在这种情况下，你可以自由地忽略它。 autograder不把风格检查计入您的分数。

% checkstyle *.java
*-----------------------------------------------------------
[WARN] Percolation.java:17:33: The instance variable 'grid_connections' must start with a lowercase letter and use camelCase. [ParameterName]
[WARN] Percolation.java:12:1: File contains tab characters (this is the first instance). Configure your editor to replace tabs with spaces. [FileTabCharacter]
Checkstyle ends with 0 errors and 2 warnings.
================================================================

在上面的例子中，样式检查器报告两个警告。 首先是实例变量grid_connections必须用小写字母，不使用camel case而是camelCase。 第二个是该文件包含制表符。 要解决第一个问题，请将该变量重命名为gridConnections。 要解决第二个问题，请配置您的IDE或文本编辑器以将空格替换为制表符。

1. Correctness

正确性测试确保您的程序按照作业的要求运行。 正确性测试在操作和输出格式上差别很大。 一个例子如下所示。

Testing methods in Percolation
*-----------------------------------------------------------
Running 15 total tests.

Tests 1 through 8 create a Percolation object using your code, then repeatedly
open sites by calling open(). After each call to open(), we check the return
values of isOpen(i, j) for every (i, j), the return value of percolates(),
and the return value of isFull(i, j) for every (i, j), in that order.

Except as noted, a site is opened at most once.

Test 1: Open predetermined list of sites using file inputs
  *  filename = input6.txt
  *  filename = input8.txt
  *  filename = input8-no.txt
  *  filename = input10-no.txt
  *  filename = greeting57.txt
  *  filename = heart25.txt
==> passed

Test 2: Open random sites until just before system percolates
  *  N = 3
  *  N = 5
  *  N = 10
  *  N = 10
  *  N = 20
  *  N = 20
  *  N = 50
  *  N = 50
==> passed

对于每个作业，您需要阅读评估细节以了解每个测试。 每个测试在底部标记为“==>通过”或“==>失败”。 当测试失败时，将向用户提供信息以协助调试。 但是，这种反馈并不总是透彻，并不足以单独解决您的问题。 您经常需要编写自己的测试来发现错误。

一个失败的测试例子如下：

Test 11: Create multiple Percolation objects at the same time
         (to make sure you didn't store data in static variables)
     isOpen(6, 9) returns wrong value [after 1 site opened]
     - student   = true
     - reference = false
     isOpen(2, 4) returns wrong value [after 1 site opened]
     - student   = true
     - reference = false
     java.lang.ArrayIndexOutOfBoundsException: 12

     Percolation.isOpen(Percolation.java:68)
     TestPercolation.checkIsOpen(TestPercolation.java:46)
     TestPercolation.check(TestPercolation.java:82)
     TestPercolation.twoPercolations(TestPercolation.java:407)
     TestPercolation.test11(TestPercolation.java:438)
     TestPercolation.main(TestPercolation.java:704)

==> FAILED

测试失败，因为Java报告IndexOutOfBoundsException。 在与此报告对应的源代码中（代码未显示），问题是渗滤对象的大小存储在一个静态变量中，当创建多个渗滤对象时会造成问题。 但是，错误信息只是提示错在哪里。

完成单个.java文件的所有测试后，将报告为该文件传递的测试总数，如下例所示。

Total: 14/15 tests passed!
================================================================

我们可以看出Percolation.java通过了15个中的14项测试！

1. Memory

内存测试确保您的程序有效利用内存。 与Correctness测试一样，内存测试在操作和格式上差别很大。 autograder使用classmexer来测量对象的内存。 我们使用-XX：-UseCompressedOops命令行选项执行，以确保内存模型与lecture中的64位内存模型一致。

未通过的测试例子如下：

Computing memory of Percolation
*-----------------------------------------------------------
Running 4 total tests.
Test 1a-1d: Check that total memory <= 17 n^2 + 128 n + 1024 bytes
                 n        bytes
--------------------------------------------
=> FAILED       64        94192   (1.2x)
=> FAILED      256      1358320   (1.2x)
=> FAILED      512      5337584   (1.2x)
=> FAILED     1024     21160432   (1.2x)
==> 0/4 tests passed
Estimated student memory = 20.00 n^2 + 184.00 n + 496.00 bytes  (R^2 = 1.000)
Total: 0/4 tests passed!
================================================================

在此示例中，autograder会创建维度为64,256,512和1024的渗透对象，并以表格形式输出总内存。 每行被标记为“=>通过”或“=>失败”。 在这种情况下，提交失败了所有4个子测试。 如果一个分测试失败，失败的程度在括号中标记。 上面，我们看到每行都标有（1.2x）。 这意味着该程序使用1.2倍的内存。 这个因素随着n的增长而不变的事实意味着这个错误可能相当小。

对于测试1a-1d，autograder提供了一个n的函数作为你允许使用的最大内存量（虽然情况并非总是如此）。

1. Timing

本课程围绕高效算法的概念而建立。 因此，我们希望您的方案不仅要解决手头的问题，而且要有效地做到这一点。 Timing测试通常以两种方式测量时间效率。 首先，它测量你的程序需要完成一组任务的原始时间。 对于许多任务，时间测试也将计算您的程序为解决给定大小的问题而进行的基本操作的数量。 作为一个例子，考虑下面的Percolation.java的Timing测试。

Timing Percolation
*-----------------------------------------------------------
Running 5 total tests.

Tests 1a-1e: Measuring runtime and counting calls to union() and find() in
WeightedQuickUnionUF. Note that connected() makes two calls to find().

For each n, a percolation object is generated and sites are randomly opened until
the system percolates. If you do not pass the correctness tests, these results may
be meaningless.
                 n   seconds     # union()              # find()
---------------------------------------------------------------------------
=> passed        8     0.00          126                   302         
=> passed       32     0.02         1530                 16646         
=> FAILED      128     0.07        22670                771594   (2.6x)
=> FAILED      512     0.50       371032              47158700   (9.4x)
=> FAILED     1024     2.15      1458534             363126570  (18.2x)
==> 2/5 tests passed

The running time (in seconds) depends on the machine on which the script runs, and may
vary each time that you submit. If one of the values in the table violates the
performance limits, the factor by which you failed the test appears in parentheses,
e.g. the 9.4x in the find() column indicates your test uses 9.4x too many calls.

Total: 2/5 tests passed!
================================================================

以秒为单位的运行时间取决于运行脚本的机器，并且每次提交时可能会有所不同。如果表格中的一个值违反了性能限制，则测试失败的因素出现在括号内，例如: 在union()列中的（9.6x）表明您的测试使用9.6倍多的调用。

与“Memory和Correctness”测试一样，Timing测试的格式因每项任务而异。对于Percolation.java，测试主要集中在操作计数上，即对union（）和find（）进行了多少次调用，但是如果程序无法解决大小为n = 1024分配的时间。

在上面的例子中，我们看到n = {128，512，1,024}的提交失败。问题是调用find()的次数过多，正如find()计数旁边的括号中所指出的那样。例如，如果n = 128，则find()调用的数量比允许的数量高2.6倍。请注意，失败因素随着n变大而增大，这意味着相对于n的运行时间的增长顺序比赋值指令中允许的增长更快。这是一个肯定的迹象，表明这个提交的方法存在根本的缺陷，这很可能需要实质性的改变。

测试中止。 耗尽时间或完成前崩溃

如果autograder无法在其分配的CPU时间内完成校正，计时或内存测试，则会中止并报告测试中止。 没有时间或完成前崩溃。 当autograder中止时，（当前）无法授予中止前通过的测试次数的部分功劳，因此您将收到此分量的0分。 这通常表示一个严重的性能错误。 如果autograder崩溃（通常是因为提交的程序抛出了某种意外的异常），您也可以得到相同的错误信息，但这是非常罕见的。