moi*_*ink 6 python docstring pylint
我知道这可以被视为基于意见的,但谷歌搜索并没有找到我希望的资源,我正在寻找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%的行 - 这是标准吗？我的docstrings非常重复,因为我的方法对数据的操作很小.例如,每个文档字符串都会倾向于声明一个参数是一个pandas数据框,并列出数据框的必需列和可选列及其含义,并在每个对数据帧执行任何操作的方法或函数中重复.
似乎我可能会在这里制造某种系统错误吗？是否有为了改进我的代码而阅读的内容的指导原则？我的文字串太长了吗？是不是有太长的文档？我应该简单地禁用pylint模块 - 太长的消息并继续我的生活吗？
哇，好问题。想要编写高质量代码的愿望确实并不常见。不过，一些关于你同事的建议。不要忽视他们的观点。他们可能不想做得不好，但你必须以某种方式将软件质量的想法与他们的价值想法联系起来。花时间与人们谈论您所编写的代码并不完全是为了您从体验中获得什么。影响组织尊重和追求软件质量对于您对公司绩效产生持久影响是必要的。否则，你写出的代码有多好都没有意义。抱歉，搁置一下；我知道这并不是你真正的问题。
在某些语言（如 Java）中，文件中只有一个类是正常的，并且该文件的名称与其包含的类相同。这在 Python 中并不正常，但我认为它提供了一些很好的指导。您希望代码易于导航，这需要在将事物尽可能紧密地放在一起和组织它们之间取得平衡，这是我们将事物分开的主要原因。因此，您可以首先检查与您的问题空间有关的这两个问题，以及代码中的想法与问题空间中的想法的一致性程度。
我使用文档字符串，但我没有尝试用 sphinx 或重组或乳胶制作它们。我在使用 Doxygen 的大型代码库中工作，但老实说，我并没有在评论中投入太多精力来使用该工具的功能，尽管我偶尔会查看 Doxygen 文档以查看是否缺少某些内容。我以前曾使用过类似表单的编码风格，但实际上我并不相信文书工作会带来价值。您的评论中所追求的重要内容与您在设计和实现中所追求的内容相同，那就是理解。每个评论中的每个词都增加了哪些理解。我不想要像名称、参数、返回这样毫无价值的填充词……我的意思是，我愿意，但只是勉强，因为我希望人们预先告诉我他们的界面是什么。我将所有这些填充词视为我愿意容忍的文书工作。我认为，让人们觉得好的评论就是好的代码是一个陷阱。它们很有帮助，但通常，如果我觉得我必须发表评论，就会发生以下两种情况之一：它是一个界面，或者是一个设计缺陷。如果我必须评论一些不是接口的东西，这可能意味着我的设计不是很清晰，或者我的实现变得混乱，因为我懒得弄清楚如何让每个函数做一件事。如果我再次来到这里，我可能会解决这个问题。
如果没有看到您的代码，我无法就如何使其高质量提供太多建议，但考虑如何定义“软件质量”可能会有所帮助。我将其定义为“更改代码有多容易”。这取决于代码可能需要的更改类型，这意味着评估代码的质量确实必须包括对可能需要的内容的一些预期。与直觉相反，实际上让代码更容易更改通常涉及不要尝试实现现在不需要的任何内容。即便如此，我经常会在最轻微的刺激下实现一些东西，尤其是用 Python。例如，实现str方法是一个好主意；通过实现eq、ne和hash使你的对象可散列甚至更酷，因为这允许你将你的对象用作字典中的键或集合的成员。
另一项（有点随机）建议是要警惕面向对象的思维。它有很多好处，但也有一些陷阱。例如，不要创建像 get_thing(self) 这样的函数。最好有一个属性，如果您需要做额外的工作，您可以创建一个 @property getter setter，这仍然会给调用者留下简单的属性访问，这更干净。我发现刚刚学习了一些面向对象思想的人倾向于认为创建大量的 get 和 set 方法是一件好事，但如果可以的话，我更喜欢将状态完全排除在设计之外，而所有这些 get 和 set 方法方法意味着对象的状态。