我刚接触Python和编程。我在大学里修了一个需要使用Python编写一些基本程序的模块。然而,上一次作业被评价为:
应该有一个标题块,包含文件名、作者名称、创建日期、修改日期和Python版本。
什么是标题块?它只是代码顶部的注释还是程序运行时会打印出来的东西?或者是其他什么东西?
我刚接触Python和编程。我在大学里修了一个需要使用Python编写一些基本程序的模块。然而,上一次作业被评价为:
应该有一个标题块,包含文件名、作者名称、创建日期、修改日期和Python版本。
什么是标题块?它只是代码顶部的注释还是程序运行时会打印出来的东西?或者是其他什么东西?
Python有一种被称为文档字符串的东西(以下是一些关于如何编写Python代码的常规规则:PEP 8),可用三个单引号'''
或三个双引号"""
来转义,非常适合于多行注释:
'''
File name: test.py
Author: Peter Test
Date created: 4/20/2013
Date last modified: 4/25/2013
Python Version: 2.7
'''
您也可以在以后(编写模块时)使用特殊变量,这些变量专门用于包含以下信息:
__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
"Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"
详细信息请参见此处的答案。
我使用这种格式,因为我正在学习,“这更多是为了我的理智,而不是必要的。”
因为我喜欢一致性。所以,我会像这样开始我的文件。
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# =============================================================================
# Created By : Jeromie Kirchoff
# Created Date: Mon August 18 18:54:00 PDT 2018
# =============================================================================
"""The Module Has Been Build for..."""
# =============================================================================
# Imports
# =============================================================================
from ... import ...
<more code...>
再次声明,这只是我的个人喜好。在一个“工作环境”中,你必须赢得每个人的支持来改变实际行为。我可以继续谈论这个问题,但我们都知道这点,至少在工作场所中。
因此,在大学设置的背景下:
标题注释出现在文件的顶部。这些行通常包括文件名、作者、日期、版本号以及文件用途和内容的描述。对于课堂作业,标题还应包括课程名称、编号、章节、教师和作业编号等信息。
嗯,这可能会被你的教授有不同的解释,请展示并询问!
"If you never ask, The answer is ALWAYS No." -> "如果你从不问,答案永远是不。"# Course: CS108
# Laboratory: A13
# Date: 2018/08/18
# Username: JayRizzo
# Name: Jeromie Kirchoff
# Description: My First Project Program.
或者使用"模块级别的下划线名称"的Python方式
__author__ = 'Jeromie Kirchoff'
__copyright__ = 'Copyright 2018, Your Project'
__credits__ = ['Jeromie Kirchoff', 'Victoria Mackie']
__license__ = 'MSU' # Makin' Shi* Up!
__version__ = '1.0.1'
__maintainer__ = 'Jeromie Kirchoff'
__email__ = 'MyGmailUser@gmail.com'
__status__ = 'Prototype'
__course__ = 'cs108'
__teammates__ = ['Jeromie Kirchoff']
__laboratory__ = 'A13'
__date__ = '2018/08/18'
__username__ = 'JayRizzo'
__description__ = 'My First Project Program.'
如果讲师需要的话,只需添加一些代码即可打印。
print('# ' + '=' * 78)
print('Author: ' + __author__)
print('Teammates: ' + ', '.join(__teammates__))
print('Copyright: ' + __copyright__)
print('Credits: ' + ', '.join(__credits__))
print('License: ' + __license__)
print('Version: ' + __version__)
print('Maintainer: ' + __maintainer__)
print('Email: ' + __email__)
print('Status: ' + __status__)
print('Course: ' + __course__)
print('Laboratory: ' + __laboratory__)
print('Date: ' + __date__)
print('Username: ' + __username__)
print('Description: ' + __description__)
print('# ' + '=' * 78)
每次调用程序时,它都会显示列表。
$ python3 custom_header.py
# ==============================================================================
Author: Jeromie Kirchoff
Teammates: Jeromie Kirchoff
Copyright: Copyright 2018, Your Project
Credits: Jeromie Kirchoff, Victoria Mackie
License: MSU
Version: 1.0.1
Maintainer: Jeromie Kirchoff
Email: MyGmailUser@gmail.com
Status: Prototype
Course: CS108
Laboratory: A13
Date: 2018/08/18
Username: JayRizzo
Description: My First Project Program.
# ==============================================================================
您的教练希望您向作业源代码的顶部部分添加一些信息,就像这样,因此您将添加注释:
####################################
# File name: ... #
# Author: ... #
# Submission: #
# Instructor: #
####################################
非常好的讨论-->Python文件的通用头格式是什么?
Python文档字符串应该简明扼要,不应包含修订历史或与当前版本行为无直接关系的任何内容。我还没有看到“man”风格的文档字符串,这也许是一样好事。
一个带有修订历史的花盆(某些修订可能比您的源代码控制版本更早)独立于源代码控制之外,回溯到在纸上阅读代码或通过电子邮件发送的日子。我们并不总是像现在这样互相联系。
使用现代IDE已经不再流行,但可以看到对于较老/较大的高级工作。在一些商店里,签到不是由编码者执行的,尤其是如果代码被“购物出去”。一些登录评论以懒惰、邋遢的方式进行。
因此,它因情况而异,但:
#! /usr/bin/python
#--------------------------------#
# optional flower box
#--------------------------------#
"""
Multiple lines of doc if required
"""
import foo
import bar
__metastuff__ = 'some value'
头部区块只是代码顶部的注释,程序运行时不打印出来。
一个例子可能如下所示:
# File name: test.py
# Author: Peter Test
# Date created: 4/20/2013
# Date last modified: 4/25/2013
# Python Version: 2.7
# Begin code
a = 1
b = 2
c = a + b
print c