I heard you liked files

— December 1, 2011 at 21:35 PST


I was going to try and be clever and do a funny riff on this whole subject, but I just can't manage it. Here's the thing. Makefile was a dumb name for a file when Stuart Feldman wrote the make utility in 1977, but you have to forgive him because file systems were quite limited back then and filenames could only be a few characters long. The pattern was <filename.ext> - 8 chars for the name, 3 for the extension. I guess config.make wouldn't fit, config.mak looked weird, so Makefile it was.

Now we have no excuse. At all.

I respect and adore Jim Weirich, but I hope he feels at least a little shame for inflicting "Rakefile" on us all. That name choice seems to have set the stage for a proliferation of copycats. Now we have an ever-growing assortment of files that helpfully tell us they are files right there in the file name. Because something siting in a directory in the file system might be something else, like maybe a turnip or a bad hair day. Capfile, Gemfile, Assetfile, Vagrantfile, Guardfile...

You may ask: What's the problem? Why should anyone care about a cute little naming convention that continues a tradition going back over 30 years?

It may not be a huge deal, but there are a couple issues with this. All of these file formats are actually a variation on a well-accepted language: Ruby. But with a name that omits the standard .rb extension, language-aware tools have no chance to help us out. Syntax highlighting? Nope. Will awk search those files for you? No way. Will RubyMine figure out the structure of the code in those files? Forget it. OK, you can add those files to all your tools' configurations, then you're good to go. Until someone creates a new Crapfile and you have to go through and update all those configurations again.

Just because your configuration file's contents are written in a DSL does not mean you should pretend it's not Ruby anymore.

I urge every maintainer of a project that uses a name like Crapfile for the configuration file to move toward using a name that is compatible with language-aware tools. If you can't think of a name yourself, allow me to suggest this:

filename.sub(/file$/, '_config.rb').downcase

UPDATE: It has been pointed out to me that RubyMine actually does a pretty good job of dealing with these file names. Not perfect, but pretty good. Anyway, I don't want to come off as bashing RubyMine (I'm spending more time with it now and it's starting to grow on me), so substitute vim or emacs or TextMate or your most-hated editor instead.

19 commentsruby

Comments
  1. Bruce Williams2011-12-01 22:55:17

    I totally agree; this is a sentiment I've expressed as well -- I call these Loudfiles. The .quietrc naming scheme suffers from the same problem.

  2. Austin Schneider2011-12-01 23:05:23

    Excellent post! I'm definitely a fan of using file extensions. Blindly following traditions seems to be an issue in lots of areas.

  3. Victor Deryagin2011-12-01 23:47:24

    Not sure about other tools, but Rake actually supports using rakefile.rb or Rakefile.rb as file name instead of Rakefile.

    Also, in programmable editors this is not much of a problem, here is what i use in Emacs to set associations for ruby-mode:

    (dolist (f '("\.\(rb\|ru\|builder\|rake\|thor\|gemspec\)\'"
                 "\(rake\|thor\|guard\|gem\|cap\|vagrant\)file\'"))
      (add-to-list 'auto-mode-alist `(,f . ruby-mode)))
    
  4. Mark Wilkinson2011-12-02 02:58:23

    make originated on Unix, which has never enforced any file name conventions about where extensions should go. Back in 1977 I think the Unix file system would have supported 14 character filenames so Stu Feldman wasn't really restricted. If you're answering the question "what do you call the file that make uses?", "makefile" seems like a pretty sensible answer to me, more so than the alternatives you suggest.

  5. Peter van Hardenberg2011-12-02 08:44:34

    Just as an exception to this rule, Procfile is neither a a DSL, nor does it contain or support any Ruby language syntax. This is by design, to keep the spec as trivial as possible.

  6. Josh Susser2011-12-02 08:51:26

    @Mark: RSTS and VMS were the first OSes I used and they were both 8.3. I started with Unix in the early '80s and I thought it was 8.3 too back then, but I could be confusing it with VMS. I do think some of Unix file naming conventions were effectively 8.3 even if the OS didn't enforce that, just because that's what people were used to, like on Mac OS X, where people have use .txt without really needing to.

  7. Jason Seifer2011-12-02 09:48:02

    I agree with your general thoughts on the naming conventions. However, in the case of Rake, I think it is a good thing that it supports the naming convention. When you consider Rake's original intention, being used as a Ruby version of make, I think it makes sense. Rake can't help that other projects copied that format as a convention.

  8. Josh Susser2011-12-02 10:08:35

    @Jason: Yep, Rake can get a pass because it's Ruby's Make. But still it was a bad precedent (as we can see from the fallout).

  9. Tim Hammerquist2011-12-02 10:19:29

    It appears current Vim versions have filetype support for [Rr]akefile and [Rr]antfile built-in. Gemfile might be considered too special purpose to be included.

    As redundant a name for a file as Makefile may be, they hardly have the monopoly on easily recognizable but extensionless file names. Some other favorites include passwd, crontab, fstab, exports, just about everything in the /usr/include/c++ tree...

    Unix as an operating system generally attaches no binding semantic value to the last few non-. characters in a file name. This sort of pigeonholing tends to come from userland (Apache, eg) or is borrowed from other operating systems (*.txt). You can rename your kernel to COMMAND.COM and, so long as you updated your bootloader, no harm would be done.

    That said, I can't think of anything in Unix history that would have prevented "config.make", "Targets" or similar from being valid, rational choices. And rake appears to be accommodating in its naming scheme.

  10. Jon Frisby2011-12-02 16:34:38

    FYI, you can call your rake configuration "Rakefile.rb" and Rake will be perfectly happy.

  11. Rein Henrichs2011-12-02 17:29:45

    But Josh... if these files don't have the word "file" in them then HOW WILL WE KNOW THAT THEY ARE FILES? QED.

  12. Lonny Eachus2011-12-02 17:56:20

    I agree that it's a bad habit, but I think it's a natural bad habit. Like when (without thinking) I name a variable "options_hash" or the like.

  13. Chris Sexton2011-12-02 19:56:43

    I guess I am in the minority, but I don't mind this convention. I like that we are consistant(ish) with the naming convention -- it is easy to spot a config file at a glance. And I don't have a better alternative. At least its consistant and good ole plain text.

    Of course if someone had a better convention that the community would buy into and follow (it's that latter part that's hard to pull off) I would be interested to hear about it.

  14. Avdi2011-12-02 20:55:43

    I laughed out loud at this one.

    And I have to say, I started out disagreeing, but you've at least halfway convinced me.

    A few quibbles:

    The leading capital is a Good Thing. Usually these files are somewhat important to the overall understanding of the project. The leading capital makes them sort to the top when listed on real operating systems, and even on those other OSes they at least stand out a bit. I want to see my Rakefile, Guardfile, etc. be prominent in the file listing.

    At least in theory, for at least a few of these I think the point is to deemphasize the fact that they are Ruby and emphasize that they are a mini-language for configuring a particular tool. For whatever that's worth.

    I agree, though, that it's hard to justify including the word "file" in the name.

    And having to teach my editor about these damn things is a little annoying, agree.

  15. formica2011-12-03 08:05:19

    Do all those misnamed files still work with appended .rb?

    There's also the Unix tradition of determining the file type by a magic value inside the file instead of by extension. Unfortunate pattern, but better than nothing. So, would a shebang without path (#!ruby) work?

  16. Kyle Drake2011-12-03 11:38:47

    I would love to have the opportunity to move all the Crapfiles out of my root folder. It's just messy! I like a clean interface to the front of my projects.

    It would be nice to at least have the option to throw them into a config folder or a .quietfolder or something like that.

  17. trans2011-12-13 09:04:48

    I created a project called Confection (http://rubyworks.github.com/confection) that can be used to house configuration for multiple tools. If tools will support it, it can help reduce the number config files that are starting to clutter up projects.

    After debating between config.rb, conf.rband 'co.rb I, of course, fell in with the "Crapfile" bandwagon, naming the file Confile (or .confile if you want to hide it). I suppose in this case it's not so bad, since the ultimate idea is to consolidate ruby-based configurations to this single file, and I will definitely make sure .rb can be added if desired. Yet I wonder, given your (reasonable) analysis, would you have named it something else?

  18. Sheldon Hearn2011-12-18 10:06:07

    Total. Non. Issue. I can't believe this made it into The Ruby Show.

  19. grosser2011-12-22 07:07:55

    Dont forget Vendorfile ;)

    maybe renaming to Rake.rb / Gem.rb would help / is also shorter and will not be confused with require 'rake'

Add Comment



Comments are styled using Markdown.