Python：什么是标题？

Python: What is a header?

提问by Victoria Mackie

I'm new to Python and programming in general. I am taking a module at university which requires me to write some fairly basic programs in Python. However, I got this feedback on my last assignment:

我是 Python 和编程的新手。我正在大学学习一个模块，该模块要求我用 Python 编写一些相当基本的程序。但是，我在上次作业中得到了以下反馈：

There should be a header block containing the file name, author name, date created, date modified and python version

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

What is a header block? Is it just comments at the top of your code or is it be something which prints when the program runs? Or something else?

什么是标题块？它只是代码顶部的注释还是程序运行时打印的内容？或者是其他东西？

回答by recursive

In this context, you are correct. A header block means a set of comments at the top of the source file that contains the requested information. It does not need to contain any code that does anything.

在这种情况下，你是对的。标题块是指包含所请求信息的源文件顶部的一组注释。它不需要包含任何可以做任何事情的代码。

回答by Bar?? Akkurt

Your instructor wants you to add some information to your assignment's source code's top section something like this, so you are right you will add comments:

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

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

回答by ustroetz

A header block are just comments at the top of the code. It doesn't print when the program runs.

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

A example could look like the following:

一个示例可能如下所示：

# 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

回答by Vyktor

There's thing called Docstring in python(and here're some conventions on how to write python code in general - PEP 8) escaped by either triple single quote '''or triple double quote """well suited for multiline comments:

在 python 中有一个叫做Docstring的东西（这里有一些关于如何编写 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
'''

You also may used special variables later (when programming a module) that are dedicated to contain info as:

您也可以稍后（在编程模块时）使用专门用于包含信息的特殊变量：

__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__ = "[email protected]"
__status__ = "Production"

More details in answer here.

在这里回答更多细节。

回答by mckenzm

Very good discussion here --> What is the common header format of Python files?

这里讨论的很好 --> Python 文件的常见头格式是什么？

The Python docstring should be concise, and not really contain revision history, or anything not directly related to the current version behaviour. I have yet to see "man" style docstrings and it may be just as well.

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

A flower box, with revision history independent of source control (as some of the revisions may pre-dateyour source control eventually) goes back to the days of reading code on paper or as emailed. We were not always as connected as we are now.

花箱，与修订历史独立的源代码控制的（如一些修订可能预先日期源控制最终）又回到了在纸上或通过电子邮件发送读取代码的日子。我们并不总是像现在这样联系在一起。

Using a modern IDE this has fallen out of favour, but can be seen for older/larger high level works. In some shops the sign in is not performed by the coder, especially if the code has been "shopped out". Some signin's are commented in a lazy, slovenly fashion.

使用现代 IDE 这已经失宠，但可以看到较旧/较大的高级作品。在某些商店中，编码员不执行签入，尤其是在代码已“购买”的情况下。一些签到的评论是懒惰的，懒散的。

So it varies, but :

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

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

import foo
import bar

__metastuff__ = 'some value'

I see the 'meta' higher up, notably in the youtube promotionals for "pycharm". People like to see it below the imports as it is really code and the imports are expected to come before the code. I can imagine it may become easy to get carried away. Sensible and informative comments in the low level code are worth way more than what is written upstairs anyway.

我看到“元”更高，特别是在“pycharm”的youtube促销活动中。人们喜欢在导入下方看到它，因为它实际上是代码，并且预计导入会出现在代码之前。我可以想象它可能很容易得意忘形。无论如何，低级代码中明智且信息丰富的注释比楼上写的更有价值。

In the real world, just do what everybody else is doing on your project and you will be fine. It is common to re-use a template anyway, or copy and paste (i.e. ripoff) from a "prototype".

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

回答by JayRizzo

My Opinion

我的看法

I use this this format, as I am learning, "This is more for my own sanity, than a necessity."

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

As I like consistency. So, I start my files like so.

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

#!/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. First line is the Shebang
   1. And I know There's no reason for most Python files to have a shebang linebut, for me I feel it lets the user know that I wrote this explicitly for python3. As on my mac I have both python2 & python3.
2. Line 2 is the encoding, again just for clarification
   1. As some of us forget when we are dealing with multiple sources (API's, Databases, Emails etc.)
3. Line 3 is more of my own visual representation of the max 80 char.
   1. I know "Oh, gawd why?!?" again this allows me to keep my code within 80 chars for visual representation & readability.
4. Line 4 & 5 is just my own way of keeping track as when working in a big group keeping who wrote it on hand is helpful and saves a bit of time looking thru your GitHub. Not relevant again just things I picked up for my sanity.
5. Line 7 is your Docstring that is required at the top of each python file per Flake8.

1. 第一行是社邦
   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 文件的顶部。

Again, this is just my preference. In a working environmentyou have to win everyone over to change the defacto behaviour. I could go on and on about this but we all know about it, at least in the workplace.

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

Header Block

标题块

• What is a header block?
• Is it just comments at the top of your code or is it be something which prints when the program runs?
• Or something else?

• 什么是标题块？
• 它只是代码顶部的注释还是程序运行时打印的内容？
• 或者是其他东西？

So in this context of a university setting:

因此，在这种大学环境中：

Header block or comments

标题块或注释

Header comments appear at the top of a file. These lines typically include the filename, author, date, version number, and a description of what the file is for and what it contains. For class assignments, headers should also include such things as course name, number, section, instructor, and assignment number.

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

• Is it just comments at the top of your code or is it be something which prints when the program runs? Or something else?

• 它只是代码顶部的注释还是程序运行时打印的内容？或者是其他东西？

Well, this can be interpreted differently by your professor, showcase it and ask!

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

"If you never ask, The answer is ALWAYS No."

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

ie:

IE：

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

If you are looking for Overkill:

如果您正在寻找 Overkill：

or the python way using "Module Level Dunder Names"

或使用“模块级 Dunder 名称”的 python 方式

Standard Module Level Dunder Names

标准模块级 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__ = '[email protected]'
__status__ = 'Prototype'

Add Your Own Custom Names:

添加您自己的自定义名称：

__course__ = 'cs108'
__teammates__ = ['Jeromie Kirchoff']
__laboratory__ = 'A13'
__date__ = '2018/08/18'
__username__ = 'JayRizzo'
__description__ = 'My First Project Program.'

Then just add a little code to print if the instructor would like.

然后，如果教师愿意，只需添加一些代码即可打印。

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)

End RESULT

最终结果

Every time the program gets called it will show the list.

每次程序被调用时，它都会显示列表。

$ 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: [email protected]
Status: Prototype
Course: CS108
Laboratory: A13
Date: 2018/08/18
Username: JayRizzo
Description: My First Project Program.
# ==============================================================================

Notes: If you expand your program just set this once in the init.py and you should be all set, but again check with the professor.

注意：如果你扩展你的程序，只需在init.py 中设置一次，你应该都设置好了，但再次与教授核对。

If would like the script checkout my github.

如果想要脚本签出我的github。