python - 关于模块长度推理和文档字符串与代码行比率的 Pylint 消息

Question

我知道这可能会被认为是基于意见的，但谷歌搜索没有找到我希望的资源，我正在寻找 Python 社区中任何既定和商定的最佳实践的链接。

我是一个组织中的中级 Python 程序员，该组织的历史非常糟糕，使用任何发明的语言编写混淆代码。我真的很想树立一个良好的编程风格和实践的例子。为此，我遵循 PEP 8，在我写的所有内容上运行 pylint，并深入思考它的每条建议，而不是简单地驳回它们。我已经将更长、更复杂的方法分解为更短的方法，部分原因是它的建议。我还按照这种风格编写了详细的文档字符串:http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

我面临的一个挑战是，虽然我不是我组织中唯一的 Python 程序员，但我似乎是唯一一个认真对待这些东西的人，而且我的同事似乎并不介意无证、重复的代码命名例如，不遵循任何特定模式。所以我不认为让他们审查我的代码或向他们学习是我最好的选择。

我刚刚从 pylint 收到了我的第一条“模块中的行过多”消息。我还没有完成模块的编写——我想在现有的类中至少再添加一个类和几个方法。我知道这个想法是一个模块应该“做一件事”但是那个“事情”还没有完全实现。

以下是pylint给我的一些统计数据:

+---------+-------+-----------+-----------+------------+---------+
|type     |number |old number |difference |%documented |%badname |
+=========+=======+===========+===========+============+=========+
|module   |1      |1          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|class    |3      |3          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|method   |27     |27         |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|function |2      |2          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+

+----------+-------+------+---------+-----------+
|type      |number |%     |previous |difference |
+==========+=======+======+=========+===========+
|code      |266    |24.98 |266      |=          |
+----------+-------+------+---------+-----------+
|docstring |747    |70.14 |747      |=          |
+----------+-------+------+---------+-----------+
|comment   |41     |3.85  |41       |=          |
+----------+-------+------+---------+-----------+
|empty     |11     |1.03  |11       |=          |
+----------+-------+------+---------+-----------+

我真的不认为 266 行代码对于一个模块来说太多了。我的文档字符串是模块中 75% 的行 - 这是标准吗？我的文档字符串非常重复，因为我的方法是对数据的小型操作。例如，每个文档字符串都倾向于声明一个参数是一个 Pandas 数据帧，并列出数据帧的必需和可选列及其含义，并且在对数据帧执行任何操作的每个方法或函数中重复。

是否有某种系统性错误似乎我可能在这里犯了？是否有关于阅读哪些内容以改进我的代码的指南？我的文档字符串太长了吗？是否有太长的文档字符串之类的东西？我应该简单地禁用 pylint 模块太长的消息并继续我的生活吗？

Answer 1

哇，好问题。拥有编写高质量代码的愿望真的不是那么普遍。不过，关于你的同事的一些建议。不要否定他们的观点。他们可能并不打算做坏事，但是您必须以某种方式将软件质量的概念与他们的值(value)概念联系起来。花时间与人们谈论您编写的代码并不仅仅是您从体验中获得的东西。影响组织尊重和追求软件质量对于您对公司绩效产生任何持久影响是必要的。否则，您编写的代码有多好都无关紧要。抱歉在旁边；我知道这不是你真正的问题。

在某些语言(如 Java)中，通常在一个文件中只有一个类，并将该文件命名为与它包含的类相同的名称。这在 Python 中是不正常的，但我认为它提供了一些很好的指导。您希望代码易于浏览，这需要在尽可能将事物紧密结合和组织起来之间取得平衡，这是我们将事物分开的主要原因。因此，您可以首先查看关于您的问题空间以及代码中的想法与问题空间中的想法的一致性的这两个问题。

我使用文档字符串，但我没有尝试用狮身人面像或重组或 latex 制作它们。我在一个使用 Doxygen 的大型代码库中工作，但老实说，我在评论中并没有花太多精力使用该工具的功能，尽管我偶尔会查看 Doxygen 文档，看看是否有我遗漏的东西。我以前曾使用过类似表单的编码风格，但实际上我并不认为文书工作会带来值(value)。在您的评论中要追求的重要事情与您在设计和实现中所追求的相同，那就是理解。每个评论中的每个词都增加了理解力。我不想要无值(value)的填充词，如 Name、Parameter、Return……我的意思是，我想要，但只是勉强，因为我希望人们预先告诉我他们的界面是什么。我将所有这些填充词视为我愿意容忍的文书工作。我认为让人们觉得好的评论会产生好的代码是一个陷阱。它们有所帮助，但通常，如果我觉得我必须评论，则发生了两件事之一:它是一个界面，或者它是一个设计缺陷。如果我必须评论一些不是接口(interface)的东西，这可能意味着我的设计不是很清楚，或者我的实现变得困惑，因为我懒得弄清楚如何让每个函数做一件事。如果我再次来到这里，我可能会清理它。

没有看到您的代码，我无法就如何使其成为高质量提供太多建议，但考虑如何定义“软件质量”可能会有所帮助。我将其定义为“代码更改的难易程度”。这取决于代码可能需要的更改类型，这意味着评估代码的质量确实必须包括对可能需要的内容的一些预期。与直觉相反，实际上使您的代码更容易更改通常涉及不尝试实现现在不需要的任何内容。即便如此，我经常会在最轻微的挑衅下实现一些东西，尤其是在 Python 中。对于 example ，实现 str 方法是个好主意；通过实现 使您的对象可以散列eq , ne 和 哈希更酷，因为它允许您将对象用作字典中的键或集合的成员。

另一项(有点随机的)建议是警惕面向对象的思维。它有很多优点，但也有一些陷阱。例如，不要创建像 get_thing(self) 这样的函数。拥有一个属性会更好，如果你需要做额外的工作，你可以创建一个@property getter setter，这仍然会给调用者一个简单的属性访问，这样更简洁。我发现刚刚学习了一些面向对象思想的人倾向于将大量的 get 和 set 方法视为一件好事，但我更喜欢将状态完全排除在设计之外，如果可以的话，所有这些 get 和 set 方法方法暗示对象的状态。