Inline comments in Ruby

Question

Is Ruby able to understand in-line comments like:

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.

Answer 1

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.

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_response = {
  headers: ["uniq_id", "email", "description"]
  rows: [
    [2345, 'foo@bar.car', 'first item'],
    [9876, 'car@bar.foo', 'second item']
  ]
} 

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

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 sawa is suggesting in his comment, if %c{} would exist I could do something like this:

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.

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

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.

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:

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

Answer 2

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.

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.

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

Addendum:

It pays to read the pry doc! A pry method 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 main pry prompt. Coupled with the the amend-line, edit, hist, play commands 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.

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 pry tab 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.

Answer 3

No, Ruby does not have inline comments.

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']