- c - 在位数组中找到第一个零
- linux - Unix 显示有关匹配两种模式之一的文件的信息
- 正则表达式替换多个文件
- linux - 隐藏来自 xtrace 的命令
我正在将一些 ( epydoc ) 文档添加到我编写的包中,并且我遇到了很多重复自己多次的实例。
def script_running(self, script):
"""Return if script is running
@param script: Script to check whether running
@return: B{True} if script is running, B{False} otherwise
@rtype: C{bool}
"""
PEP257说:
One-liners are for really obvious cases.
还有
The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).
是否有关于何时在单行(描述)和完整参数/返回字段之间划清界限的一般准则或标准做法?
或者在生成文档时,我应该包括每个功能的每个适用字段,不管它看起来有多么重复?
奖励问题:从语法上讲,描述 script
参数的最佳方式是什么?
最佳答案
您正在寻找的一般指南就在 PEP257 中。在您引用的内容中,也许您只需要实际操作即可。
您的函数非常适合单行文档字符串(“非常明显的案例”):
def script_running(self, script):
"""Check if the script is running."""
通常,如果您说一个函数正在检查某些内容,则意味着它将返回 True
或 False
,但如果您愿意,可以更具体一些:
def script_running(self, script):
"""Return True if the script is running, False otherwise."""
再次全部在一行中。
我可能还会更改函数的名称,因为没有必要强调函数在其名称(脚本)中的作用。函数名应该是甜美的、简短的并且对函数的作用有意义。可能我会选择:
def check_running(self, script):
"""Return True if the script is running, False otherwise."""
有时 function-name-imagination 厌倦了所有的编码,但无论如何您都应该尽力而为。
对于多行示例,让我从 google guidelines 中借用一个文档字符串:
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
这可能是“总结其行为并记录其参数、返回值、副作用、引发的异常以及调用时间限制(如果适用)”的一种方式.
您可能也有兴趣查看此 example of pypi project它应该用 Sphinx 记录.
我的 2 美分:指南旨在让您了解您应该做什么和不应该做什么,但它们不是严格的规则,您必须盲目执行跟随。所以最后选择你觉得更好的。
我想澄清一下另一个答案中提到的关于使用文档字符串达到最大行长度的内容。
PEP8告诉您“将所有行限制为最多 79 个字符”,即使最后每个人都做了 80 个字符。
这是 80 个字符:
--------------------------------------------------------------------------------
这可能是一种边缘情况,您真正需要的只是一个有点长的句子:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 characters
limit.
"""
就像一个单行文档字符串,这意味着用于非常明显的情况,但在您的编辑器上(有 80 个字符的限制)是多行的。
关于python - 文档字符串 - 一行与多行,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/9392096/
如何使用 SPListCollection.Add(String, String, String, String, Int32, String, SPListTemplate.QuickLaunchO
我刚刚开始使用 C++ 并且对 C# 有一些经验,所以我有一些一般的编程经验。然而,似乎我马上就被击落了。我试过在谷歌上寻找,以免浪费任何人的时间,但没有结果。 int main(int argc,
这个问题已经有答案了: In Java 8 how do I transform a Map to another Map using a lambda? (8 个回答) Convert a Map>
我正在使用 node + typescript 和集成的 swagger 进行 API 调用。我 Swagger 提出以下要求 http://localhost:3033/employees/sear
我是 C++ 容器模板的新手。我收集了一些记录。每条记录都有一个唯一的名称,以及一个字段/值对列表。将按名称访问记录。字段/值对的顺序很重要。因此我设计如下: typedef string
我需要这两种方法,但j2me没有,我找到了一个replaceall();但这是 replaceall(string,string,string); 第二个方法是SringBuffer但在j2me中它没
If string is an alias of String in the .net framework为什么会发生这种情况,我应该如何解释它: type JustAString = string
我有两个列表(或字符串):一个大,另一个小。 我想检查较大的(A)是否包含小的(B)。 我的期望如下: 案例 1. B 是 A 的子集 A = [1,2,3] B = [1,2] contains(A
我有一个似乎无法解决的小问题。 这里...我有一个像这样创建的输入... var input = $(''); 如果我这样做......一切都很好 $(this).append(input); 如果我
我有以下代码片段 string[] lines = objects.Split(new string[] { "\r\n", "\n" }, StringSplitOptions.No
这可能真的很简单,但我已经坚持了一段时间了。 我正在尝试输出一个字符串,然后输出一个带有两位小数的 double ,后跟另一个字符串,这是我的代码。 System.out.printf("成本:%.2
以下是 Cloud Firestore 列表查询中的示例之一 citiesRef.where("state", ">=", "CA").where("state", "= 字符串,我们在Stack O
我正在尝试检查一个字符串是否包含在另一个字符串中。后面的代码非常简单。我怎样才能在 jquery 中做到这一点? function deleteRow(locName, locID) { if
这个问题在这里已经有了答案: How to implement big int in C++ (14 个答案) 关闭 9 年前。 我有 2 个字符串,都只包含数字。这些数字大于 uint64_t 的
我有一个带有自定义转换器的 Dozer 映射: com.xyz.Customer com.xyz.CustomerDAO customerName
这个问题在这里已经有了答案: How do I compare strings in Java? (23 个回答) 关闭 6 年前。 我想了解字符串池的工作原理以及一个字符串等于另一个字符串的规则是
我已阅读 this问题和其他一些问题。但它们与我的问题有些无关 对于 UILabel 如果你不指定 ? 或 ! 你会得到这样的错误: @IBOutlet property has non-option
这两种方法中哪一种在理论上更快,为什么? (指向字符串的指针必须是常量。) destination[count] 和 *destination++ 之间的确切区别是什么? destination[co
This question already has answers here: Closed 11 years ago. Possible Duplicates: Is String.Format a
我有一个Stream一个文件的,现在我想将相同的单词组合成 Map这很重要,这个词在 Stream 中出现的频率. 我知道我必须使用 collect(Collectors.groupingBy(..)
我是一名优秀的程序员,十分优秀!