添加注释

良好的注释内容可以帮助调试代码

你可能已经在这门课程的一些代码中见到了注释。注释是计算机会忽略的代码。它们可以让你针对你所写的代码留下备注（供自己或其他程序员查看）。向代码中添加注释可以帮助你（和其他人）调试代码。当代码出现错误时，可以将注释注明的代码 应该 实现的作用与代码 实际 上实现的作用进行对比。

在 Python 中，你可以通过输入 # 添加注释。这一行 # 后面的所有内容都将变成注释。其他语言使用不同的字符来表示注释，但是所有语言都提供了某种注释方法。

程序员可以参考各种指南，了解如何编写描述性但是不唐突的注释。在此纳米学位课程的整个学习过程和你的整个编程生涯中，你都需要遵守这一原则。以下提示可以帮助你添加有意义的注释：

1) 不要为“作用明显的代码”添加注释

随着你的编程技能不断增长，“作用明显的代码”的含义也会改变，但是一般而言，如果代码含义清晰，无需解释，则不需要为其添加注释。以下注释就是多余的：

print "Hello" # prints hello

直接写 print "Hello" 就够了。

2) 定义函数时添加注释

所有函数开始定义时都需要添加注释，描述预期的输入和输出结果，并解释函数的作用。这样可以帮助其他人了解函数的目的。例如：

def isLeapYear(year):
    # takes a number as input and outputs True if the number
    # represents a leap year and False otherwise

在 Python（并非所有语言）中，你还可以使用 docstring 为函数添加注释。docstring 是多行字符串，充当函数的描述性注释，但是当代码执行时，计算机会保留这些内容，并且在代码运行时用户可以访问这些内容。

def isLeapYear(year):
    '''takes a number as input and outputs True if the number
    represents a leap year and False otherwise'''

在 IPND 中，你可以选择使用注释或 docstring，但是应该保持一致。类（将在第 3 阶段介绍） 也应该遵守这一规则。

3) 及时更新注释

如果你更改代码后，没有更新注释的话，则很容易令人困惑。确保及时更新注释，避免阅读代码的其他人（或者你自己很长时间之后再去阅读这些代码）感到迷惑不清。毕竟注释的主要目的就是当代码出现错误时，帮助其他人了解你的代码应该实现的作用。如果你的注释提供了错误的信息，则很难实现这一目的!

4) 简明扼要

注释应该简短，仅解释代码最重要的信息。如果你需要写很长的注释来解释不容易看懂的代码部分，那么可能需要重新思考解决问题的方法了。通常，完善的代码只需少量的注释。写的很差的代码可能需要大量注释去解释！