Comments can be used appropriately to introduce classes and provide
documentation. But used incorrectly, they mask readability and process
problems by further obfuscating already unreadable code.
- Comments within method bodies.
- More than one comment per method.
- Comments that restate the method name in English.
- Todo comments.
- Commented out, dead code.
# Text for each answer in order as a comma-separated string
This comment is trying to explain what the following line of code
does because the code itself is too hard to understand. A better
solution would be to improve the legibility of the code.
Some comments add no value at all and can safely be removed:
# Deliver the invitation
If there isn’t a useful explanation to provide for a method or class
beyond the name, don’t leave a comment.
explaining variable to make obfuscated lines easier to read in
- Extract method to
break up methods that are difficult to read.
- Move todo comments into a task management system.
- Delete commented out code and rely on version control in the event
that you want to get it back.
- Delete superfluous comments that don’t add more value than the
method or class name.
The canonical reference for writing fantastic Rails applications from authors who have created hundreds.
Work with us to make a new Rails app, or to maintain, improve, or scale your existing app.