问题标签 [self-documenting-code]

是否值得学习该约定，或者它是否会损害可读性和可维护性？

例如，在 Java 中，@Override注解不仅提供了对覆盖的编译时检查，而且还提供了出色的自文档化代码。

我只是在寻找文档（尽管如果它是诸如 pylint 之类的检查器的指标，那是一个奖励）。我可以在某处添加注释或文档字符串，但是在 Python 中指示覆盖的惯用方式是什么？

为了保持一致性，我总是将注释（以 JavaDoc 的形式）应用于所有方法和类，即使它们是简单的 getter 和 setter 方法或非常小的包装类。但我也在努力编写经常使注释变得多余的自记录代码；即只在需要的地方写注释（在这样做之前，试着重写代码，这样你就根本不需要注释了）。因此，这两种方法似乎相互矛盾。

那么描述方法或类的注释应该以一致的方式应用，还是应该仅在定义中含义不完全清楚时才编写此类注释？

这两个概念似乎违反直觉。争论的一方面认为评论对可读性造成的伤害，以及违反 DRY（如果评论甚至保持最新）。但是，掷硬币，有必要为您的代码提供良好的 API 文档，以便其他人可以使用您的库。

我见过的每一个为生成 API 文档而设计的工具（JSDoc、PDoc 等）都使用大量的空间来提供该文档。我需要提供 API 文档，我不需要将我的一半 LOC 设置为特殊格式的注释，以便 JSDoc 可以读取它。

我目前正在考虑使用像Jekyll这样的基本降价工具，并将此文档放在 /doc 文件夹中，从我的代码中完全删除它。有没有其他人找到对他们有用的解决这个问题的方法？

我创建了一个小类，它允许我使用强类型枚举的枚举器作为标志（组合）。我正在使用 type_traits 进行底层类型检测，因此它也应该是稍微类型安全的，并且主要在编译时处理。但是，我想知道这是否真的值得。

我现在可以写类似的东西

并且程序员将看到他只能使用 Mode 中的枚举器（例如 Mode::Read），而且他不能将任何其他枚举与 Mode 结合使用。你认为这是更好的方法吗？

，我不确定人们是否会欣赏它？

我正在 nodejs + Express 中开发一个 REST API，我同时在 README 文件中记录我的 API，我想知道是否可以自动化它。例如给定：

我希望它自动生成这个

我找到了一个很好的关于 JQL 的教程列表，包括关于如何编写插件的参考 [1]。是否已经或可以向 JQL 查询添加注释？

例如，为了记录我的项目，我希望能够记录我们的 sprint 'number' 与 jira sprint 'id' 不同； sprint = 777 (* Agile sprint #50 *)

//更新 ; 我注意到 Sprint ID 显然不是在打开 sprint 时立即创建的。根据浏览报告页面，我们刚刚开始了一个新的冲刺，但没有编号...

1.[]; ; ; ; ; X.JQL 回顾！在一篇文章中查看所有内容；; http://blogs.atlassian.com/2013/03/jql-recap/

我正在从 Swift 迁移到 Kotlin，到目前为止我很喜欢它。但是，我习惯于声明这样的方法（假设引用的方法存在并且有效）：

并像这样称呼他们：

这是精美的自我记录，读起来像英语。然而，在 Kotlin 中，类似的方法是这样的：

使用名为inRect. 但是当我调用它时它变得更糟：

在这里，我们看到了最大的问题：人们可能仅通过阅读这条线就可以猜出它myRect是一个矩形，圆形将在其中绘制。然而，什么是true？它可能是抗锯齿，是的，但也可能是是否不透明地绘制它，或者是关于是否绘制它的一些切换！无论如何，我可以列举更多为什么 Swift 和 Objective-C 程序员喜欢他们的方法调用标签的原因，但我已经说明了我的观点。

有什么方法可以在 Kotlin中的方法调用上启用标签？

我正在寻找一种方法来澄清我的 Lua 函数的合同。特别是参数应该具有哪些属性。

为了说明我的问题，一些代码片段具有我当前代码的典型结构。使用两个公共函数构造新“实例”的函数。

一个函数，它接受一个应该具有相同签名（或超集）的参数。

调用后面的函数

这段代码的问题是，如果textPrinter不printSomeStuff查看printSomeStuff. 虽然使用此示例很容易做到这一点，但通常情况并非如此（在我的场景中强制在文件之间跳跃）。newTextPrinter除了名称相似之外，也没有任何迹象表明可以通过 获得合适的值。

有没有办法让代码更加自我记录并更好地揭示作者的意图？

我更喜欢一种轻量级的方法，并且不尝试模拟基于类的继承。同样，代码优先于文档，否则，工具可以理解的格式的文档优先于自由格式。很明显，我可以只写“参数textPrinter需求print和printBig公共函数”之类的注释，但是如果没有告诉您您在文档中犯的错误，或者当您重构代码并忘记更新它时，这很容易出错。

我正在使用 Lua 5.0 并且对该语言非常陌生。

假设我们在一个实现文件处理的对象中。我想编写代码以便于阅读。

很难判断返回类型的代码示例，尤其是当有多个嵌套函数调用时：

通过引入一个澄清变量，这个例子更具可读性：

理论上，第二个版本可以执行相同的操作，因为编译器必须暂时存储 doCreateAction() 的结果（可能在一些隐藏的、匿名的、短期的临时变量中）。分配给命名变量时，这段代码会变慢吗？