Author : Mike Dane
Last Updated : November, 2017
As you continue to sharpen your Ruby skills and get more and more comfortable writing programs, you'll eventually become really good at reading code. Just by looking at a line or two you'll be able to tell what the program is doing, and what's going to happen.
But, in a lot of cases, merely relying on the code to properly explain or document itself can be ineffective, and often times in the course of writing a program you'll want to mark things down or explain why you're doing things a certain way. This is where comments can be your best friend.
A comment is basically a piece of code in the program that Ruby will ignore. Unlike all of the really cool and interesting commands we've learned so far, comment's actually don't do anything... Well at least not as far as the computer is concerned.
You can write a comment like so
/''' multi line comment ''' # single # line # comment
As you can see there's two basic types of comments: single line and multi line.
Single Line Comments
In a single line comment the rules are that anything that comes after the # on the same line is ignored by Ruby when it executes. A lot of times developers will use these to temporarily remove a line of code by putting the # in front of it.
These single line comments are also often used to describe or give more context to a line of code. As a general rule it's always preferred that you write clear, descriptive code so that comments like this aren't necessary, but every once in a while a well placed comment can clear up confusion.
Generally a comment like the one described above, is placed either directly above the line of code it's describing, or immediately to the right of it. I always prefer to put these types of comments on top of the line of code because otherwise you'll find that one single line of code ends up being really long, which can get annoying.
Single line comments are also commonly used as TODO markers. If you see a comment that says
TODO, that generally means that this is a part of the code which has yet to be implemented, and therefore the developer who’s working on the program has TO DO it.
Multi line comments
Multi line comments have a starting and an ending tag, as you can see in the code above. These are generally more convenient for commenting out large blocks of code.
A lot of times you’ll see developers put different kinds of documentation in comments like this. In fact, in many programs, comments are used to help generate documentation.
Sometimes you’ll encounter code files with more comments than actual executable code, and it’s because all of the official documentation for the codebase is generated in part from the comments in each file.
Using Comments Wisely
There are no hard set rules for when you should and shouldn’t use comments when writing programs. In a lot of cases it’s just personal preference.
As I mentioned above however it’s usually a bad idea to rely on comments to make your code understandable. If you’re looking at a line of code, and can’t tell what it’s doing without reading a corresponding comment, then, except for in rare cases, that line of code can probably be re-written.
Personally, I really like using comments to comment out parts of my code when I’m writing it. As you write more and more complex programs, a lot of times you’ll run into problems where the code is crashing at certain points. In cases like this, I will generally comment out, that is to say, surround with comments, the code I think is causing the problem, and if the code starts working again then I’ve found the culprit.
At the end of the day comments are a great tool which can help with documenting code and giving you an easy way to quickly remove code without actually deleting it.
As we go forward in the course I would encourage you to start using comments to enhance your code and look for ways they can make your life easier as a developer!