解析文档字符串是一种好习惯吗?

时间:2016-07-27 12:55:32

标签: python

我有一些带有指令的python方法。例如,要测试的参数组合。在我的代码的计数部分,我使用解析器作为我使用的函数的doc-string,以便不再需要配置文件。我需要的信息仅包含在函数doc字符串中。我想知道这是否是行业中的一个好的和常见的做法?

更新:我有很多实验要做,由功能代表。对于每个函数,我都有一些测试用例(不同的函数不同)。当我创建函数时,定义了测试用例。我把它们放在doc字符串中,并在我进行测试时解析它们。

def my_function1(param1,param2)
    '''param1: 10, 20, 40, 60; param2: 5, 10, 20, 40;'''

    return something 


def my_function2(param1,param2,param3)
    '''param1: 10, 20, 40, 60; param2: 5, 10, 20, 40; param3: 100, 200'''
    return something 

.
.
.

在这种情况下,我很方便将测试用例保存到doc字符串中。但我不确定解析文档字符串是一种安全的做法。

1 个答案:

答案 0 :(得分:1)

编辑:以下是PEP建议: https://www.python.org/dev/peps/pep-0257/#specification

我相信这不是常见做法,我的直觉是这也不是好习惯。

首先,来自Python标准库模块的一些示例Docstrings。

当我为组合键入帮助时:

Signature:
combinations(iterable, r) --> combinations object

Docstring:
Return successive r-length combinations of elements in the iterable.

combinations(range(4), 3) --> (0,1,2), (0,1,3), (0,2,3), (1,2,3)

这是总和的帮助:

Signature:
sum(sequence[, start]) -> value

Docstring:
Return the sum of a sequence of numbers (NOT strings) plus the value
of parameter 'start' (which defaults to 0).  When the sequence is
empty, return start.

这些文档字符用英语详述。

根据Python核心开发人员的文档字符串的目标似乎是明确地展示如何使用这些方法,并清除任何疑问。我建议你的练习是错误的,因为你将不同的目标,不同类型的逻辑混合到你的文档中。

如果我是你,我会孤立并分离你的目标,而不是将所有内容组合到你的文档字符串中。我会将测试用例的逻辑和配置保存在为该逻辑指定的不同位置。

一般来说,在编程方面,我认为保持不同的目标是最佳实践和#34;封装

但是,我应该承认,通过阅读您的问题,我并不相信我完全理解您的要求,或者您在测试和配置方面做了什么。