Python：什么是标头？

Question

我是 Python 和一般编程的新手。我正在大学学习一个模块，该模块需要我用 Python 编写一些相当基本的程序。然而，我收到了关于我上次作业的反馈：

应该有一个包含文件名、作者姓名、创建日期、修改日期和python版本的标题块

什么是标题块？它只是代码顶部的 cmets 还是程序运行时打印的内容？还是别的什么？

Answer 1

这里讨论得很好 --> What is the common header format of Python files?

Python 文档字符串应该简明扼要，并且不真正包含修订历史记录，或与当前版本行为不直接相关的任何内容。我还没有看到“男人”风格的文档字符串，它可能也一样。

具有独立于源代码控制的修订历史的花盒（因为某些修订最终可能早于您的源代码控制）可以追溯到阅读纸上代码或通过电子邮件发送的时代。我们并不总是像现在这样联系在一起。

使用现代 IDE，这已失宠，但可以在较旧/较大的高级作品中看到。在某些商店中，登录不是由编码人员执行的，尤其是在代码已“被淘汰”的情况下。一些登录的评论以一种懒散、邋遢的方式。

所以它会有所不同，但是：

#! /usr/bin/python
#--------------------------------#
# optional flower box  
#--------------------------------#
""" 
Multiple lines of doc if required
"""

import foo
import bar

__metastuff__ = 'some value'

我看到“meta”更高，尤其是在“pycharm”的 youtube 宣传中。人们喜欢在导入下面看到它，因为它实际上是代码，并且导入应该在代码之前。我可以想象它可能会变得很容易得意忘形。无论如何，低级代码中的明智和信息丰富的 cmets 比楼上写的更有价值。

在现实世界中，只需按照其他人在您的项目中所做的事情，您就会没事的。无论如何，重复使用模板是很常见的，或者从“原型”复制和粘贴（即盗版）。

Answer 2

我的意见

我使用这种格式，因为我正在学习，“这更多是为了我自己的理智，而不是必需品。”

因为我喜欢一致性。所以，我就这样开始我的文件。

#!/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...>

1. 第一行是Shebang
   1. 我知道There's no reason for most Python files to have a shebang line，但对我来说，我觉得它让用户知道我为python3明确编写了这个。在我的 Mac 上，我同时拥有 python2 和 python3。
2. 第 2 行是编码，再次说明一下
   1. 当我们处理多个来源（API、数据库、电子邮件等）时，有些人会忘记
3. 第 3 行更多的是我自己对最大 80 个字符的可视化表示。
   1. 我知道“哦，天哪，为什么？！？”再次，这使我可以将代码保持在 80 个字符以内，以实现视觉表示和可读性。
4. 第 4 行和第 5 行只是我自己的跟踪方式，因为当在一个大团队中工作时，将谁写在手边是有帮助的，并且可以节省一些时间查看您的 GitHub。与我为了理智而选择的东西无关。
5. 第 7 行是您的 Docstring，每个 Flake8 的每个 python 文件的顶部都需要它。

同样，这只是我的偏好。在working environment 中，您必须赢得所有人的支持才能改变事实上的行为。我可以继续说下去，但我们都知道，至少在工作场所是这样。

标题块

• 什么是标头块？
• 是否只是代码顶部的 cmets 还是程序运行时打印的东西？
• 还是别的什么？

所以在大学环境中：

Header block or comments

标题 cmets 出现在文件的顶部。这些行通常包括文件名、作者、日期、版本号，以及文件用途和内容的描述。对于班级作业，标题还应包括课程名称、编号、部分、讲师和作业编号等内容。

• 它只是代码顶部的 cmets 还是程序运行时打印的内容？还是别的什么？

好吧，您的教授可以对此有不同的解释，展示它并询问！

“如果你从不问，答案总是不。”

即：

# Course: CS108
# Laboratory: A13
# Date: 2018/08/18
# Username: JayRizzo
# Name: Jeromie Kirchoff
# Description: My First Project Program.

如果您正在寻找 Overkill：

或使用"Module Level Dunder Names"的python方式

标准模块级 Dunder 名称

__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__ = 'Jahomie04@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: Jahomie04@gmail.com
Status: Prototype
Course: CS108
Laboratory: A13
Date: 2018/08/18
Username: JayRizzo
Description: My First Project Program.
# ==============================================================================

注意：如果您扩展您的程序，只需在 init.py 中设置一次即可，您应该已设置完毕，但请再次与教授确认。

If would like the script checkout my github.

Answer 3

有一个叫做Docstring in python的东西（这里有一些关于如何编写python代码的约定-PEP 8）被三重单引号'''或三重双引号"""转义，非常适合多行 cmets:

'''
    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"

更多详情请见answer here。

Answer 4

标题块只是代码顶部的 cmets。程序运行时不打印。

一个示例可能如下所示：

# 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

Answer 5

您的教师希望您在作业的源代码顶部添加一些信息，如下所示，所以您是对的，您将添加 cmets：

####################################
# File name: ...                   #
# Author: ...                      #
# Submission:                      #
# Instructor:                      #
####################################

Answer 6

在这种情况下，你是对的。标头块是指源文件顶部的一组 cmets，其中包含所请求的信息。它不需要包含任何执行任何操作的代码。