Ruby 中的内联注释

Inline comments in Ruby

提问by Paul

Is Ruby able to understand in-line comments like:

Ruby 是否能够理解内嵌注释，例如：

my_array = ['first', /* 'second', */ 'third', 'fourth']

?

?

Update:

更新：

I asked not about what is /* */ in Ruby and why I receive an error, but about presence of in-line comments in any available form at all. /* */ were given only as example of in-line comments known to me.

我问的不是 Ruby 中的 /* */ 是什么以及为什么我会收到错误，而是询问是否存在任何可用形式的内嵌注释。/* */ 仅作为我所知道的内嵌注释示例。

采纳答案by Douglas F Shearer

No, Ruby does not have inline comments.

不，Ruby 没有内联注释。

Comments of this style have a tendency to reduce readability, since they makes the code harder to follow.

这种风格的注释有降低可读性的倾向，因为它们使代码更难以理解。

In your case it would be best to split your array items into separate rows and comment out the one row.

在您的情况下，最好将您的数组项拆分为单独的行并注释掉一行。

my_array = ['first',
#           'second',
            'third',
            'fourth']

回答by Tony Zielinski

I'd just like to add that rdoc — Ruby's built-in documentation builder — can utilize the comments within your code to build an initial set of documentation. From what I've understood in my recent reading, the "Ruby way" suggests that your code should be readable and self-explanatory, but that comments are a valuable and simple way to build documentation in early development, before sending a project off to a proper documentation team.

我只想添加 rdoc — Ruby 的内置文档构建器 — 可以利用代码中的注释来构建初始文档集。根据我在最近阅读中的理解，“Ruby 方式”表明您的代码应该是可读且不言自明的，但是在将项目发送到一个适当的文档团队。

On the subject of inline comments, my use-case is that I find myself working on longish one-liners in irb before committing them to my properly formatted source files. Perhaps many people don't mind working with line-breaks in their development environment, but with my limited knowledge of the toolset at the moment, I'm finding it tedious to repeat previous commands. I'm nearly certain this is due to my failure to grok the tools at hand, be it irb, pry and what-have-you. At the moment, I'm wrapping any code which I desire to comment inline inside of a string object, which I must later remove or "uncomment" by removing the string wrapper.

关于内联注释的主题，我的用例是我发现自己在将它们提交到我正确格式化的源文件之前在 irb 中处理较长的单行。也许很多人不介意在他们的开发环境中使用换行符，但是由于我目前对工具集的了解有限，我发现重复以前的命令很乏味。我几乎可以肯定这是由于我没有掌握手头的工具，无论是 irb、pry 还是你有什么。目前，我正在包装任何我希望在字符串对象内内联注释的代码，我稍后必须通过删除字符串包装器来删除或“取消注释”。

Take it or leave it, but those are my two cents! Keep on Rubying on!

接受或离开它，但那是我的两分钱！继续 Rubying！

Addendum:

附录：

It pays to read the prydoc! A prymethod is bound to every object, including the main. Calling it executes a sub-shell in the current prompt that allows you to analyze any object within the current scope. It is available in any context, including the mainpry prompt. Coupled with the the amend-line, edit, hist, playcommands in Pry, this sates my desire for inline comments, although I'm still unaware of any feature in pry which will load a previous command into the current prompt's input for editing.

阅读pry文档是值得的！甲pry方法势必每一个对象，包括main。调用它会在当前提示中执行一个子 shell，允许您分析当前范围内的任何对象。它可以在任何上下文中使用，包括mainpry 提示。再加上Pry 中的amend-line, edit, hist,play命令，这满足了我对内联注释的渴望，尽管我仍然不知道 pry 中的任何功能会将前一个命令加载到当前提示的输入中进行编辑。

Invoking the text editor tends to distract me a fair bit, not only because it removes the contents of the shell buffer from visibility on a single display (e.g. laptop), but especially since it removes all of the helpful prytab completions and commands. I'd like to see pry, or another REPL which enables use of the cursor across multiple lines, since I'm still finding the need to use one-liners.

调用文本编辑器往往会让我分心，不仅因为它从单个显示器（例如笔记本电脑）上的可见性中删除了 shell 缓冲区的内容，而且特别是因为它删除了所有有用的pry选项卡完成和命令。我希望看到 pry 或另一个可以跨多行使用光标的 REPL，因为我仍然发现需要使用单行。

回答by equivalent8

Read the whole thing before you down-vote :)

在你拒绝投票之前阅读整件事:)

To be honest you shouldn't be using comments at all, your code should be self explanatory.

老实说，您根本不应该使用注释，您的代码应该是不言自明的。

I know this may seems off topic but hear me out as a suggestion why they wont ever implement these kind of comments in Ruby.

我知道这似乎离题了，但请听我说为什么他们永远不会在 Ruby 中实现这些类型的评论。

I stumble upon this question because I'm processing our clients ugly API. The JSON request procesed to Ruby code looks something like this

我偶然发现了这个问题，因为我正在处理我们的客户丑陋的 API。处理到 Ruby 代码的 JSON 请求如下所示

api_response = {
  headers: ["uniq_id", "email", "description"]
  rows: [
    [2345, '[email protected]', 'first item'],
    [9876, '[email protected]', 'second item']
  ]
} 

So in my script I want to collect all the uniq ids:

所以在我的脚本中，我想收集所有的 uniq id：

JSON.parse(api_response)
  .fetch('rows')
  .collect { |application_row| application_row.at(0) }

it would be nice to have some ability to comment what the at(0)is fetching. Like sawais suggesting in his comment, if %c{}would exist I could do something like this:

如果有能力评论at(0)正在获取的内容，那就太好了。就像sawa在他的评论中建议的那样，如果%c{}存在的话，我可以做这样的事情：

JSON.parse(api_response)
  .fetch('rows')
  .collect { |application_row|  %c{uniq_id}; application_row.at(0) }

...but then I realized I'm just being stupid. The self code should self explain my intention

……但后来我意识到我只是愚蠢。自我代码应该自我解释我的意图

uniq_ids = JSON.parse(api_response)
             .fetch('rows')
             .collect { |application_row| application_row.at(0) }

In some cases this is not an option, so maybe this would do the trick:

在某些情况下，这不是一种选择，所以也许这可以解决问题：

JSON.parse(api_response)
  .fetch('rows')
  .collect { |application_row| uniq_id = application_row.at(0) }

...yes this will lead to usage of unused local variable, however in this case this is ok as the readability of code would benefit not affecting performance too much.

...是的，这将导致使用未使用的局部变量，但是在这种情况下，这是可以的，因为代码的可读性将不会对性能产生太大影响。

in Pauls case he just want to remove one element from the Array. I guess he probably wants it for debugging purpose, but the general idea is that Ruby force you to write you as clean code as possible and remove anything that won't be used in production.

在 Pauls 的案例中，他只想从数组中删除一个元素。我猜他可能希望它用于调试目的，但总体思路是 Ruby 迫使您编写尽可能干净的代码并删除任何不会在生产中使用的代码。

solution for this could be

解决方案可能是

my_array =  ['first']
# my_array += ['second']
my_array += ['third', 'fourth']

Is this ugly ? well yes, that's the general thought is that you should re-factor this before you commit, enforcing you to remove ugly code and remove unnecessary stuff along before hitting production.

这丑吗？是的，这是普遍的想法，您应该在提交之前重新考虑这一点，强制您在投入生产之前删除丑陋的代码并删除不必要的东西。

---

---

update 2019 05

更新 2019 05

I see this answer is -1 now, It was posted 2014. It's 2019 And I still have the same opinion :) If you write a comment you failed to write code that clearly display the intention :)

我现在看到这个答案是 -1，它是在 2014 年发布的。现在是 2019 年，我仍然有相同的意见:) 如果您写评论，则说明您没有编写清楚显示意图的代码:)

There are definitely cases where comment is needed. But proper reaction of developer should be: "oh my god there is a comment ! I need to pay attention!"

肯定有需要评论的情况。但是开发者的正确反应应该是：“天哪，有评论！我需要注意！”

I'm currently 12 year of professional experience in the field. And seen this over and over in projects: If there is a comment all over the code developers will stop seeing comments as valuable information and just not read them.

我目前在该领域有 12 年的专业经验。并且在项目中一遍又一遍地看到这一点：如果代码中到处都是注释，开发人员将不再将注释视为有价值的信息，而不会阅读它们。

But in principle there is no single use case of "let's place a comment here" that cannot be solved with a good code/architecture design :)

但原则上，没有一个“让我们在这里发表评论”的用例不能通过良好的代码/架构设计来解决:)

Just to quote Martin Fowler:

引用Martin Fowler 的话：

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

任何傻瓜都可以编写计算机可以理解的代码。优秀的程序员会编写人类可以理解的代码。