From: Gregory Brown <gregory.t.brown@...>
Date: 2007-01-20T05:24:12+09:00
Subject: Conventions for project organization?

Hi folks,

I'm going to writing a short blog entry for the O'Reilly blog about
ruby conventions for project layout.  I think this is relatively
valuable, as it greatly simplifies the ability to audit projects and
possibly contribute to them.

(I've been researching a *lot* of different projects for various
things in Ruport lately)

I think I pretty much follow good practices when it comes to my
project organization, but I'd like to hear what people think and also
if they have anything to add.

Here are a few of the things I think are relevant:

== Structure ==

bin/  :  any scripts or executables

lib/   :  source files.

conventionally,

Ruport::Data::Table is in

lib/ruport/data/table.rb

alternatively, the class could be included in any file lower down the chain:
(e.g. lib/ruport.rb or lib/ruport/data.rb)

ext/ : C sources for extensions

doc/: documentation

test/:  All tests and test data.  Tests should begin with
test_class_name, however an older convention is tc_class_name with
ts_all.rb loading all your tests.

main directory:
Rakefile, main documentation files such as README

== Library requires ==

Do these in the correct logical places, so if you hav

lib/
  ruport.rb
  ruport/
   data.rb
   data/
       table.rb
       record.rb


Then ruport.rb should include:

require "ruport/data"

and data.rb should include:

require "ruport/data/table"
require "ruport/data/record"

There are of course exceptions to this...

== Tests ==

One test per method, ideally, mapping method name to test.
Additional tests for bug reports, edge cases, etc.
( I usually use a name like test_ensure_table_append_accepts_arrays)

or some really long name describing the problem I'm checking for

== Organization of methods in source / tests ==

This i'm not sure about.  Some people do alphabetical, some do
alphabetical by concept, some do just concept, some no organization.
I think that it is helpful when the tests follow in the same order of
the source, though.

What do people think about this.

== Other things? ==

I am aiming for something short and simple.  I don't want to overwhelm
people with a ton of rules to follow, but a few basic conventions for
those who haven't really looked into other projects yet would be
helpful for all of us, I think.

However, if anyone thinks they've got some really important tips to
share, let me know.