Question

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

我是一个组织中的中级Python程序员，他在编写每种语言的混淆代码方面都有相当糟糕的历史。我真的想树立好的编程风格和实践的例子。为此，我正在关注PEP 8，在我写的所有内容上运行pylint，并深入思考每个建议，而不是简单地解雇它们。我将更长，更复杂的方法分解为更短的方法，部分原因在于它的建议。我还按照这种风格写了详细的文档字符串：http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

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

我刚刚获得了第一个＆＃34;模块中的太多行＆＃34;来自pylint的消息。我没有写完模块 - 我想在现有的类中添加至少一个类和几个方法。我知道这个想法是一个模块应该做一件事＆＃34;但那＆＃34;事情＆＃34;尚未完全实施。

以下是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％的行 - 这是标准吗？我的docstrings非常重复，因为我的方法对数据的操作很小。例如，每个文档字符串都倾向于声明一个参数是一个pandas数据帧，并列出数据帧的必需列和可选列及其含义，并在每个对数据帧执行任何操作的方法或函数中重复。

我可能会在这里制作某种系统错误吗？是否有为了改进我的代码而阅读的内容的指导原则？我的文字串太长了吗？是不是有太长的文档？我应该简单地禁用pylint模块 - 太长的消息并继续我的生活吗？

Answer 1

哇，好问题。渴望编写高质量的代码并不是那么常见。但是，有关你的同事的一些建议。不要忽视他们的观点。他们可能不打算做坏事，但你必须以某种方式将软件质量的概念与他们的价值观联系起来。花时间与人们谈论你所编写的代码并不是关于你从经验中得到什么。影响组织尊重和追求软件质量对于您对公司的绩效产生持久影响是必要的。否则，你写的代码有多好无关紧要。对不起;我知道这不是你的问题。

在某些语言中，如Java，在文件中只有一个类，并将该文件命名为与其包含的类相同，这是正常的。这在Python中并不常见，但我认为它提供了一些很好的指导。您希望代码易于导航，这需要在尽可能紧密地将事物放在一起并组织它们之间取得平衡，这是我们分离事物的主要原因。因此，您可以首先回顾一下有关问题空间的这两个问题，以及代码中的想法与问题空间中的想法保持一致的程度。

我使用doc字符串，但我没有尝试用sphinx或重组或乳胶制作它们。我在使用Doxygen的大型代码库中工作，但老实说，在我的评论中我并没有花费太多精力来使用该工具的功能，尽管我偶尔会在Doxygen文档中查看是否存在我遗漏的内容。之前我曾经使用过类似表格的编码风格，但实际上并没有出售文书工作带来的价值。在您的评论中，重要的是与您在设计和实施中所采用的相同，这就是理解。每条评论中的每个单词都会增加理解力。我不想要像名字，参数，回归那样毫无价值的填充词...我的意思是，我这样做，但只是勉强，因为我希望人们告诉我他们的界面是什么。我认为所有这些填充词都是我愿意容忍的文书工作。我认为这是一个陷阱让人觉得好的评论可以做出很好的代码。他们有所帮助，但通常情况下，如果我觉得我必须发表评论，其中有两件事情正在发生：它是一个界面，或者它是一个设计缺陷。如果我必须评论一些不是界面的东西，这可能意味着我的设计不是很清楚，或者我的实现变得混乱，因为我太懒了，无法弄清楚如何让每个函数做一件事。如果我再次来到这里，我可能会清理一下。

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

另一个（有点随机的）建议是警惕面向对象的思维。它有很多好处，但有一些陷阱。例如，不要使用get_thing（self）这样的函数。拥有一个属性更好，如果你需要做额外的工作，你可以创建一个@property getter setter，这仍然会给调用者带来一个简单的属性访问，这样更清晰。我发现那些刚刚学会了一些面向对象的想法的人往往会把很多get和set方法看作是一件好事，但是如果可以的话，我更愿意将状态完全从设计中驱除，并且所有这些都得到并设置方法意味着对象的状态。

Answer 2

@ChipJust在评论中有很好的答案，所以我将使用list：

评论很棒，但一旦您需要大量评论，代码结构可能会出现问题
一般情况下，您需要在任何yoir模块入口点中使用detiled docstring，例如记录您向其他人公开的API，但不一定是整个代码
单元测试在您的组织中扮演什么角色？你不能只用docstrings来争取质量，测试也很有用。当测试失败，文档字符串死亡或者无声地错过/过时时，测试也会显而易见。

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

2 个答案:

关于模块长度推理的Pylint消息以及文​​档字符串与代码行的比率

2 个答案:

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