Use Comments in Ruby
The comments are lines in computer programs that are avoid by compilers and interpreters. You will use comments to create your programs easier for different programmers to know by using them to produce additional context or clarification regarding what each part of a program is doing.
You will use comments to clarify why you selected a particular solution, or even prevent a problematic or incomplete a part of your program from executing temporarily while you work out a fix.
The some comments may stay within the code forever, like those that explain context, whereas different comments are often temporary, like notes you permit yourself whereas you are building your program.
Let’s check out the way to use comments in Ruby programs to leave notes, as well as the way to use them as a debugging tool.
Comment Syntax and Usage
Comments in Ruby begin with a hash mark (#) and continue to the end of the line, like this:
While it is not needed, you ought to place a blank space after the hash mark to enhance the comment’s readability.
When you run a program, you will not see any indication of comments within the code; the Ruby interpreter ignores them entirely. Comments are within the source code for humans to read, not for computers to execute.
These comments provide you with a general idea of what every section of the program will and the way it works.
In a program that iterates over an array and displays its contents as an HTML list, you would possibly see comments like this, that provides a very little additional clarification regarding what the code does:
You may not be familiar with things like map and join yet, however the comments provide you an idea of how this program should work and what the output may seem like. Try it out, Place this code in a file called sharks.rb and run it:
You’ll see the program’s output:
<ul> <li>hammerhead</li> <li>great white</li> <li>dogfish</li> <li>frilled</li> <li>bullhead</li> <li>requiem</li> </ul>
Notice you do not see the comments, since the interpreter ignored them. However the output probably matched what you were expecting. Comments are a excellent communication tool, particularly once the person reading the comments is new the language.
Comments ought to be created at constant indent as the code they commenting. That is, a class definition with no indentation would have a comment with no indentation, and each indentation level following would have comments that are aligned with the code it’s commenting.
For example, here could be a Ruby implementation of a Magic 8-Ball game. The computer can provides a random answer to an question you raise.
Notice that the comments are indented at constant level of indentation because the code in every section.
Comments are supposed to help programmers, whether it is the original programmer or someone else using or collaborating on the project. This means the comments must be maintained just like the code. A comment that contradicts the code is worse than no comment at all.
When you’re just starting out, you may write lots of comments to help you understand what you’re doing. But as you gain more experience, you should be looking to use comments to explain the why behind the code as opposed to the what or how. Unless the code is particularly tricky, looking at the code can generally tell what the code is doing or how it is doing it.
For example, this kind of comment isn’t that helpful once you know Ruby:
This comment reiterates what the code already does, and while it doesn’t affect the program’s output, it is extra noise when you’re reading code.
Sometimes you’ll need to write comments that are a little more detailed. That’s what block comments are for.
You will use block comments to clarify additional difficult code or code that you just don’t expect the reader to be familiar with. These longer-form comments apply to some or all of the code that follows, and are indented at same level as the code.
In block comments, each line begins with the hash mark followed by single space for readability. If you need to use over one paragraph, they must be separated by a line that contains one hash mark.
Here is an example of a block comment from the Sinatra web framework’s source code. It provides some context to other developers regarding how this particular code works:
Block comments are great when you need to thoroughly explain pieces of code. However, you should try to avoid over-commenting your code, as those comments could be redundant and create additional noise. Trust other programmers to understand Ruby code unless you are writing for a particular audience. Comments should add context, not duplicate the code.
Ruby has an alternative syntax for multi-line comments, but it’s rarely used. Here’s an example:
The =begin and =end lines must be at the start of the line. They cannot be indented. It’s for this reason that you will rarely see this used.
Let’s check out inline comments next.
Inline comments occur on same line of a statement, following the code itself. Like other comments, they start with a hash mark, followed by one white-space character for readability.
Generally, inline comments seem like this:
Inline comments should be used meagerly, however are often effective for explaining difficult or non-obvious of code. They will even be helpful if you think that you will not remember a line of the code you’re writing within the future, or if you’re collaborating with somebody who you know may not be familiar with all aspects of the code.
For example, if you don’t use a lot of math in your Ruby programs, you or your collaborators may not understand that the subsequent creates a complex number, thus you will wish to include an inline comment regarding that:
You can also use inline comments to explain the reason behind doing something:
Comments that are made in line should be used only when necessary and when they can provide helpful guidance for the person reading the program.
Commenting Out Code for Testing
In addition to using comments as the simplest way to document code, you’ll use the hash mark to comment out code that you just don’t wish to execute whereas you’re testing or debugging a program you’re presently making. Sometimes, when you experience errors once adding new lines of code, you will wish to comment some of them out to see if you’ll troubleshoot the problem through the method of elimination.
For example, within the Magic 8-Ball game, maybe you wish to stop the sport from running once more as a result of you are simply fascinated by ensuring that the code evaluates the solution properly. You can simply comment out the line of code that starts the sport again.
Comments also let you try alternatives while you’re determining how to implement a solution in your code. For example, you may want to try a couple of different approaches when working with arrays in Ruby. You can use comments to test each approach and determine which one you like the most:
Commenting out code helps you to attempt completely different programming strategies as well as help you find the source of an error through systematically commenting out and running parts of a program.
Using comments within your Ruby programs will create programs additional clear to humans, including your future self. Including acceptable comments that are relevant and helpful makes it easier for others to collaborate with you on programming projects. They’ll also help you understand code you wrote within the future after you come back your project after a long period of time.