andyw8 / do_by

Automatically expiring TODO notes in Ruby

DoBy

This is a proof-of-concept of automatically-expiring TODO notes.

• HackerNews thread
• Reddit /r/programming thread

TODO comments can be a plague on a software codebase. They begin as a good intention to go back and do something, but are easily forgotten or ignored. They can hang around in code for years. And unlike stale code, they're not excecuted, so they never cause anything to break.

DoBy makes your TODO comments complain when they become stale. You add a note using a special TODO method, providing a date which you to defer until. When your code runs, the expiry date on the TODO will be checked, and it will raise an error if it's overdue.

This forces you to look at the TODO task again. If it's no longer relevant, you can delete it. If you can fix it, you fix it. If you cannot fix it right now, change the date to something in the future to re-visit it again.

In addition to TODO, you could also add tasks for FIXME and OPTIMIZE

Example

You can add reminders to specs or the actual implementation, anywhere that will be executed:

class Article < ActiveRecord::Base
  TODO 'add named scopes', '2014-06-01'
  OPTIMIZE 'improve this code', '2014-10-01'
  FIXME 'some_method is broken', '2014-05-01'

  has_many :comments
  # ...
end

The date can be anything parseable by Ruby's DateTime.parse method - 2014-06, June, etc.

Enable DoBy checks by setting ENABLE_DO_BY=1 in the environment. (It's made that way so it doesn't run by default on production environments. You wouldn't want accidents to happen!)

Before that date, everything will run as normal. After that date, the code will raise an exception:

DoBy::LateTask: 'fix this' is overdue (2014-06-01)

FAQ

Why not just use the features my IDE/editor has for tracking TODOs?

You need to either remember to check these periodically, or choose to always display them when you run you tests. If these stick around for more than a short time you'll start ignoring them.

Enhancements

Several people have suggested that this concept could exist as a script which scans over the code for TODOs. That means the TODOs could stay as actual comments, supplemented with some metadata, e.g.:

# TODO [20140601] Fix Me

This script could run as part of a Continous Integration process so that it fails the build if there are overdue TODOs.

Installation

Add this line to your application's Gemfile:

gem 'do_by', github: 'andyw8/do_by'

And then execute:

$ bundle

Similar Projects

• FixMe
• DoBy (Scala)
• todo_or_die

Coverage

• Beware the Siren Song of Comments

Contributing

1. Fork it ( https://github.com/andyw8/do_by/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

do_by's Issues

I think a deprecation warning in advance would be good

Consider piggybacking on Rails rake:notes

The rake:notes task could be set to exit with a non-zero return value if any overdue tasks are found.

Should not allow notes without a date

Override rake notes to make it work with this gem's annotations

Unfortunately rake notes won't find the annotations made for this gem.
I hacked this together

echo "require File.expand_path('../lib/tasks/notes', __FILE__)" >> Rakefile

The file lib/tasks/notes is

class SourceAnnotationExtractor
  def find_in(dir)
    results = {}

    Dir.glob("#{dir}/*") do |item|
      next if File.basename(item)[0] == ?.

      if File.directory?(item)
        results.update(find_in(item))
      else
        pattern =
            case item
            when /\.rb$/
              /[#]{0,1}\s*(#{tag}):?\s*(.*)$/
            when /\.(builder|coffee|rake)$/
              /#\s*(#{tag}):?\s*(.*)$/
            when /\.(css|scss|sass|less|js)$/
              /\/\/\s*(#{tag}):?\s*(.*)$/
            when /\.erb$/
              /<%\s*[#]{0,1}\s*(#{tag}):?\s*(.*?)\s*%>/
            when /\.haml$/
              /-\s*#\s*(#{tag}):?\s*(.*)$/
            when /\.slim$/
              /\/\s*\s*(#{tag}):?\s*(.*)$/
            else nil
            end
        results.update(extract_annotations_from(item, pattern)) if pattern
      end
    end

    results
  end
end

The original is from railties-4.1.6/lib/rails/source_annotation_extractor.rb

I changed the REs for .rb, Rake and .erb. They recognize both the # TAG and the TAG form. I don't have builder, coffee, haml, slim files to test with so I didn't touch their RE.

This is hardly the right way to do it but I had little time to think about it. Hopefully somebody will put it together in a more proper form.

More graceful behavior on expiration

Rather than raising an exception at some unknown point in the future, crashing some poor user's program and ruining his day...

Rather than that, what if do_by logged a warning message, and continued normal execution flow?

Based on HackerNews/Reddit comments, I think this would make people happier / increase adoption of do_by.

Considering implementing as a git hook

See http://githooks.com/

Disable by default

Default to not running the checks, set ENABLE_DO_BY=1 to run them.

https://news.ycombinator.com/reply?id=7759953&whence=item%3fid%3d7759878

Syntax change

TODO 20140601 fix me could suggest the date refers to when the task note was added, rather than when it's due. So for clarity, perhaps use:

TODO by 20140601 fix me