[Rake-devel] About that new magic comment ...

James M. Lawrence quixoticsycophant at gmail.com
Sun Feb 27 23:10:02 EST 2011


Assume the following tasks were written for Rake 0.8.x.

  # This comment describes a non-toplevel-task.
  task :complex_task do
    # ...
  end

  # For internal use only -- washes laundry, takes out trash, other
  # crap.
  task :house do
    # ...
  end

  #
  # I prefer this comment style.
  #
  task :style do
    # ...
  end

#### output of rake --tasks:

  rake complex_task  # This comment describes a non-toplevel-task.
  rake house         # crap.

Fortunately my own commenting style avoids this problem. Others will
likely encounter some annoyance (small or possibly great).

One could make the comment-grabber smarter, but the question is: How
should a programmer document a top-level task? There is already an API
method for doing so: desc. The new comment-to-desc feature does not
solve an actual problem or deficiency.

There could hundreds of these new magic-comment 'desc's cropping up,
making the --tasks output useless. Even one newly-public comment could
be an issue (think of a programmer making a veiled complaint about a
co-worker). A programmer may have good reason to use '#' instead of
'desc'. Why should a new version of Rake suddenly dismiss that reason?

Surely there is someone out there who wrote

  (0...1000).each do |i|
    # blah blah ...
    task "blah#{i}" do
      # ...
    end
  end

#### rake --tasks output:

  rake blah0         # blah blah ...
  rake blah1         # blah blah ...
  rake blah10        # blah blah ...
  rake blah100       # blah blah ...
  rake blah101       # blah blah ...
  rake blah102       # blah blah ...
  rake blah103       # blah blah ...
  rake blah104       # blah blah ...
  rake blah105       # blah blah ...
  rake blah106       # blah blah ...
  rake blah107       # blah blah ...
  rake blah108       # blah blah ...
  rake blah109       # blah blah ...
  rake blah11        # blah blah ...
  rake blah110       # blah blah ...
  rake blah111       # blah blah ...
  rake blah112       # blah blah ...
  ...

In exchange for annoying that programmer, what do we get in return?
Usually compatibility is purposefully broken in order to fix a flaw.
What is the flaw in 'desc'? Why is '#' better than 'desc'?

The worst-case scenario is an auto-generated web page of the --tasks
output. With the new Rake, a password in the comments gets exposed.

Previously '#' meant internal documentation for a non-top-level task.
Now it means public documentation for a top-level task, an effective
alias of 'desc'. For internal docs, leave a space between the comment
and the task definition. That is natural for me, but requiring all
programmers to do that in all Rakefiles seems rather unnatural.


More information about the Rake-devel mailing list