MENU

「1」 Annotation

September 8, 2018 • Coding at SCIE

无论是否是为了考试,你总应该保持一个良好的注释习惯——你总不希望一个月后看着自己的代码一脸懵逼

1. 文档描述

你应该在文档的开头使用多行注释描述一下作者,时间,以及程序的目的。在考试中你还需要标出你的考号与题目,如

'''
Student ID:16000, Question 1, 8/9/2018
Do XXXX
'''

(当然,你需要把Do XXXX改成你程序实际的功能)

2. 注释

2.1. 函数

对于Function的注释只有一个目的——说清楚他是干什么的。一个不错的例子是:

def sub1():
    # Do X and return a price.

(当然你肯定要把Do X换成有意义的描述)

对于Procedure(虽然我个人不喜欢这个定义,但是为了考试嘛总该有点牺牲),一个不错的例子是

def sub2():
    # Verification input and output bill.

2.2. 变量

对于变量的注释,你应该说清楚这个变量是什么以及他的类型,比如:

bill = 0 # Variable bill (integer).

你同样可以在操作变量时写个注释,如:

bill = bill + 1 # Increase bill.

2.3. CALL/RETURN

call的时候可以简单描述一下函数的作用,比如:

money = account_check() # Get user's money (integer).

同样,在return的时候也可以简单描述返回了什么东西,如:

    return bill # Return user's money (integer).

2.4. 其他情况

这篇文章是面向完全没有接触过代码的你们的,无脑列举出所有的情况显然是十分愚蠢的。简单地说,你需要在这写地方加上注释
· 你不怎么理解的代码
· 别人不怎么样理解的代码
· 提醒自己/别人注意的代码
· 非常重要的代码
· 容易混淆的变量
· 在程序中定义好,但可能会由于种种原因需要后期修改的变量(e.g. 学生管理系统许可输入的最大年龄)
· 一切你想要解释一下的代码

出于考试目的,我本人十分建议你尽可能的多使用注释

Ref: pep-0257, pep-0008
【PEP与授课内容冲突时在不改变本意的情况下尽量靠近授课内容】

By AlanJin16046, NO WARRANTY

Tags: None
Leave a Comment

已有 1 条评论
  1. #(高兴)耶终于写完了这篇,相信大家还沉迷在疯狂刷注释当中无法自拔吧!下一篇选题写什么呢……欢迎建议唷!