我在一篇关于Python编码指南的文档中偶然发现了以下Python源文件的标题格式:
#!/usr/bin/env python
"""Foobar.py: Description of what foobar does."""
__author__ = "Barack Obama"
__copyright__ = "Copyright 2009, Planet Earth"
这是Python世界中标头的标准格式吗?我还可以在标题中添加哪些字段/信息?Python gurus分享你的关于好的Python源码标题的指南:-)
发布于 2012-02-10 17:13:33
我非常喜欢最小的文件头,我的意思是:
如果这是以标准方式分组的可执行脚本
#!
行)进行,例如: import os # standard library
import sys
import requests # 3rd party packages
from mypackage import ( # local source
mymodule,
myothermodule,
)
即。三组导入,它们之间只有一个空行。在每个组中,对导入进行排序。最后一个组,从本地源导入,可以是如图所示的绝对导入,也可以是显式相对导入。
其他的一切都是在浪费时间和视觉空间,并且具有积极的误导性。
如果您有法律上的免责声明或许可信息,它会放入一个单独的文件中。它不需要感染每个源代码文件。你的版权应该是其中的一部分。人们应该能够在你的LICENSE
文件中找到它,而不是随机的源代码。
诸如作者和日期之类的元数据已经由您的源代码管理维护。没有必要在文件本身中添加相同信息的不太详细、错误和过时的版本。
我不认为每个人都需要将任何其他数据放入所有的源文件中。您可能有一些特定的要求,但根据定义,这些事情只适用于您。它们在“推荐给每个人的通用标题”中没有一席之地。
发布于 2017-12-05 04:00:19
上面的答案真的很完整,但如果你想要一个快速而肮脏的标题来复制和粘贴,请使用以下代码:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""Module documentation goes here
and here
and ...
"""
为什么这是一个好的选择:
另请参阅:https://www.python.org/dev/peps/pep-0263/
如果您只是在每个文件中编写一个类,那么您甚至不需要文档(它将放在类doc中)。
发布于 2021-11-10 16:26:01
我在一些项目中使用的是Linux机器的第一行中的这一行:
# -*- coding: utf-8 -*-
作为DOC和作者的功劳,我喜欢多行中的简单字符串。下面是一个来自的示例
# -*- coding: utf-8 -*-
"""Example Google style docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
也可以很好地添加:
"""
@Author: ...
@Date: ....
@Credit: ...
@Links: ...
"""
其他格式
""“
:mod:parrot
-- Dead parrot =================================== ..module::parrot :platform: Unix,Windows :synopsis:分析并复活死了的鹦鹉。。。模块作者::Eric Cleese eric@python.invalid作者::John Idle john@python.invalid“
#!/usr/bin/env python3第1行# -*-编码: utf-8 -*-第2行utf#创建者: name_版本3行#创建日期:日期/月/时间版本# of_the_creator ='1.0‘# ---------------------------------------------------------------------------
https://stackoverflow.com/questions/1523427
复制相似问题