关于模块长度推理和文档字符串与代码行之比的Pylint消息
我知道这可能会被认为是基于意见的，但谷歌搜索没有找到我所希望的资源，我正在寻找Python社区中任何已建立和商定的最佳实践的链接。
我是一个中级Python程序员，在这个组织中，我有过用每种语言编写混淆代码的糟糕历史。我真的很想给大家树立一个好的编程风格和实践的例子。为此，我遵循PEP8，在我写的每一件事上运行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模块太长的消息，然后继续我的生活？
回答 2
Stack Overflow用户
发布于 2017-10-04 14:49:26
哇，问得好。想要写出高质量的代码并不是那么普遍。不过，还是有一些关于你同事的建议。不要忽视他们的观点。他们可能并不打算做一件糟糕的工作，但你必须以某种方式将软件质量的想法与他们的价值想法联系起来。花时间与人们讨论你写的代码并不全是你从经验中得到的东西。影响组织尊重和追求软件质量对于您对公司绩效产生任何持久的影响都是必要的。否则，你写的代码再好也无关紧要。抱歉，我知道这不是你真正的问题。
在一些语言中，例如Java，在一个文件中只有一个类是正常的，并且该文件的名称与它所包含的类相同。这在Python中是不正常的，但我认为它提供了一些很好的指导。你希望代码易于导航，这需要在尽可能紧密地将事物放在一起和组织它们之间取得平衡，这是我们将事物分开的主要原因。因此，您可以从检查关于问题空间的这两个关注点开始，以及代码中的想法与问题空间中的想法的一致性程度。
我使用文档字符串，但我没有尝试使用sphinx、restructured或latex来创建它们。我工作的代码库很大，使用Doxygen，但老实说，我并没有在我的评论中花太多精力来使用该工具的功能，尽管我偶尔会查看Doxygen文档，看看我是否遗漏了什么。我以前使用过类似表单的编码风格，但我实际上并不相信文书工作能带来价值。在你的评论中要做的重要事情与你在设计和实现中要做的事情是一样的，那就是理解。每条评论中的每个单词都增加了什么理解。我不想要没有价值的填充词，比如Name、Parameter、Return……我的意思是，我想要，但只是不情愿地，因为我想让人们预先告诉我他们的界面是什么。我认为所有这些填充性的话都是我愿意容忍的文书工作。我认为这是一个陷阱，让人们觉得好的评论就是好的代码。它们有帮助，但通常情况下，如果我觉得我必须评论，两件事中的一件正在发生:这是一个界面或它是一个设计缺陷。如果我不得不评论一些不是接口的东西，这可能意味着我的设计不是很清晰，或者我的实现变得混乱，因为我太懒了，不知道如何让每个函数做一件事。如果我再来这里，我可能会来清理一下。
如果不看你的代码，我不能给出太多关于如何使其高质量的建议，但这可能有助于思考你如何定义“软件质量”。我将其定义为“更改代码有多容易”。这取决于代码可能需要的更改类型，这意味着评估代码的质量确实必须包括对可能需要的内容的一些预期。与直觉相反的是，实际上让你的代码更容易修改通常涉及到不尝试实现任何现在不需要的东西。尽管如此，我经常会在最轻微的情况下实现一些东西，特别是在Python中。对于example，实现字符串散列方法是一个很好的想法；通过实现eq、ne和hash来使对象可散列甚至更酷，因为这允许您将对象用作字典中的键或集合的成员。
另一个(有点随机的)建议是要警惕面向对象的思维。它有很多优点，但也有一些陷阱。例如，不要制作像get_thing(self)这样的函数。最好是有一个属性，如果你需要做额外的工作，你可以做一个@property getter setter，这仍然会给调用者留下一个简单的属性访问，这要干净得多。我发现刚刚学习了一些面向对象思想的人倾向于将创建大量的get和set方法视为一件好事，但如果可以的话，我更喜欢将状态完全从设计中驱动出来，所有这些get和set方法都隐含着对象的状态。
Stack Overflow用户
发布于 2018-06-04 06:15:09
@ChipJust在评论中有很好的答案，所以我将求助于列表：
- 注释很棒，但代码结构可能会有问题一旦你需要那么多的注释
- 通常，你会希望在任何一个模块入口点中都有一个带索引的文档字符串，例如记录你暴露给其他人的API，但不一定是整个代码
- 单元测试在你的组织中扮演着什么角色？你不能只用文档字符串来争取质量，测试也是非常有用的。测试还可以清楚地表明，当它们失败时，文档字符串会消失，或者正在静默地丢失/过时。
https://stackoverflow.com/questions/46557680
复制相似问题
腾讯云开发者
