Ruby Notes : a Tool for Group Projects in Rails

Maybe you’re new to programming? 
Maybe you’re new to programming in teams?

Ruby has a very opinionated community around comments in code — “the code should be readable and speak for itself” — but assuming you’re new to that community and maybe even new to the concept of code comments at all, lets move past opinions and talk about why comments can be useful, especially in team work.

Comments can be really effective tools for communication and collaboration. You can create logical sections of a file to quickly find certain types methods and functionality. You can indicate when values are intentionally limited (like numerical rounding) or formatted in a specific way that might be unexpected. Larger comments in code (block comments) are intended to explain why a given chunk of code is necessary and not what it does or how it works. It’s also important to realize that if you’re writing comments, maintaining those comments is just as important as maintaining the code.

Some comments are purely meant to be temporary and are a way to directly communicate intentions to teammates or yourself as the project progresses. These comments can be created with built-in tags that help you find them in your project later. These comments are intended to be actionable items that translate to code implementation and can be removed when the task is complete.

This post is going to cover three built in comment tags and how you can create your own.


Built-in Tags

TODO — # TODO: — Can be used to keep track of general action items, next steps or unexpected things that come up as solutions play out. You can indicate where features may be weak or can be made more robust. You can indicate where features can be implemented when dependencies are finally merged.

FIXME — # FIXME: — Can be used to indicate where something is broken or is of higher priority than a To-Do item. It’s good for features in need of some love that are currently vital but may be buggy or insufficient.

OPTIMIZE — # OPTIMIZE: —Generally for improving resource management and efficiency.

Note: the comment tags don’t hold any functionality in accordance with their suggested use. They are meant for readability and general quick understanding when one is discovered in the code.


Retrieving Notes

In the terminal from within your project directory root, you can run 
rake notes to retrieve all of the comments in your code with the built-in tags.

You can also retrieve all notes of a specific tag with the following:
rake notes:todo
rake notes:fixme
rake notes:optimize

In the final section of this post, you’ll learn how to retrieve custom tags.
(spoiler alert: rake notes:custom ANNOTATION=CUSTOMTAG )

You can also retrieve all comments (with or without tags) in your code by running rake notes:custom though, you’re probably not looking to do this. If you’re trying to stick to ‘no comments in code’ opinion, and all your actionable notes are complete, this can help you find where you have regular code comments or commented out garbage code.

For the following ruby code (which contains the only tagged-notes in my project):

  it "This test doesn't do anything but hold notes" do
# TODO: something
# FIXME: something is broken
# TODO: something else
# OPTIMIZE: something is slow
# TESTME: custom tag
# TODO the colon does not affect the note
# HEY-JOHN this note is for you
end

Note: the comments TESTME and HEY-JOHN are custom tags and do not appear in the following steps ( — jump to last section for more information)

The terminal output of running rake notes is:

spec/models/using_notes_spec.rb:
* [ 5] [TODO] something
* [ 6] [FIXME] something is broken
* [ 7] [TODO] something else
* [ 8] [OPTIMIZE] something is slow
* [10] [TODO] the colon does not affect the note

You can see that the file path leads the collection of notes and that each note appears in order presented in that file, and includes the line number.

If we had notes in more than one file, the output would appear as follows:

spec/models/using_notes2_spec.rb:
* [ 5] [TODO] this is a note in another file
* [ 6] [TODO] this too
spec/models/using_notes_spec.rb:
* [ 5] [TODO] something
* [ 6] [FIXME] something is broken
* [ 7] [TODO] something else
* [ 8] [OPTIMIZE] something is slow
* [10] [TODO] the colon does not affect the note
* [11] [TODO] _  it can be anything

In your working IDE, it’s probably most effect if you use the project/file text search to look for your notes. This will provide you with direct links to those lines of code and actionable tasks.


Custom Note Tags

You can also make your own custom note tags!

To find them you’ll run the command:
rake notes:custom ANNOTATION=CUSTOMTAG

Your code can now include a note like:
 # CUSTOMTAG: this is my custom note

These custom notes can be useful for all sorts of things!

One way is to tell your teammates that you’re currently working on a task and they shouldn’t touch that piece of functionality yet. This might come up if you need to quickly merge so the team can be up to date and move on individually from a common (but maybe not production ready) ground.
 Your custom tag might look something like:
# K-WIP: this is K's Work In Progress method — please ignore!
and be retrieve like:
rake notes:custom ANNOTATION=K-WIP

Another way is to indicate where teammates can pick up where you left off. Say, for example, you’re making a navigation bar html partial that links to all sorts of paths that other teammates will be implementing functionality for. You can create all the links or leave static text where the links would be and create notes in your various route/controllers/views/models files where that next person should pick up the remaining work.
# HEY-JOHN: please make this static text a link to your new path for the profile page
and then John, after being informed you left these notes for him, can retrieve them with this command:
 rake notes:custom ANNOTATION=K-WIP

One task I unfortunately find myself writing is # TESTME. This one is my shortest-lived comment and I preface writing any non-Test-Driven-Development functionality with this, even if I’m going to write a test immediately after. Sometimes, when working on view features, I build in model functionality, but only drive the development with feature tests. This is is a great time, in my opinion, to use a comment like this so you don’t forget to make a model test as well. Sometimes for better or worse, you just end up spiking some code to get through a complicated problem, but if you track it with a note, at least you know exactly where to go back to and test. These comments are also my top priority to address before I submit code to my team; the team is not responsible to initially test your contribution, you are.

In the example used earlier, running 
rake notes:custom ANNOTATION=TESTME

would return the following:

spec/models/using_notes_spec.rb:
* [9] custom tag

NOTE: the tag name does not appear in the result, only the file path(s) and the line number(s).

THE DOWNSIDE:

Unfortunately, running rake notes will NOT retrieve these custom notes, so be careful and make sure the team is aware of custom notes and has a standard set of custom tags if choosing to use this tool. Communication is the key to a successful project, so communicate the use of custom note tags in pull requests and tag anyone the notes are targeted for.