Preface: This is not much about how to structure code within files. I have that down. This is more of the topic of organization of your source tree. Hopefully someone will just say, "Here's a great link on the topic." However, firsthand opinions on the subject are welcome too.
So I've done a bit of digging on this subject and find tons of material on simple structure. I guess the assumption is that, by the time you need to deal with the problems of the size of your codebase, you'll already know the answer. However, even the IDEs seem to be waging a holy war on how these projects should be structured (which is NOT what I wanted to start in this thread).
Java enforced the package structure in the language. Kudos for that. Eclipse then lets you use projects to have (potentially) independent -- we'll call them 'buckets' in this example -- buckets of related code. Intellij has distinct but similar concepts with 'modules' within a singleton instance of a 'project'. If you want another project, you're essentially starting from scratch.
However, RubyMine offers no such modules in ruby apps, and by default just wants to slam everything into the root directory. It allows Directories, so one could essentially just pick some arbitrary tree structure and run with it. This implies to me their intent was that all classes have access to all other classes within your project. This might have some resolution through the use of Ruby 'modules', or might just be an honor-system pattern of "don't reference that stuff."
So, to put it succinctly, say I were building a 'foo' and a 'bar' concept, and both depend on a 'util' class. maybe I'll deploy them as gems, maybe I won't. I could:
Slam them all into one RubyMine project and just ignore the fact that 'foo' and 'bar' have no reason to be aware of each other.
Put each in its own RubyMine project. This seems like a real pain if there is any concurrent development. First of all, 'util' would have to be packaged separately and then included as an external resource in the other projects.
Neither seems particularly appealing. Thougts?
I'd develop all three independently, then make util a gem. In the Gemfile for each of foo and bar, you can give a path to the gem so that you can develop them all concurrently without the pain of messing with version numbers and so forth (for production, you would then point it to the real gem on Rubygems or at some git repository).
For project structures, check out the Ruby Packaging Standard and Gem Patterns.
Related
I'm trying to set up a working ruby project with guard-rspec.
I've mixed together the general method of a tutsplus tutorial with some new syntax as described in the RSpec videos and another post. The project can be found in the stack-overflow-question branch on github.
I'm also trying to practice namespacing as described in Programming Ruby 1.9. So eventually I'd like to have example.rb in my lib/example/ directory.
There's 4 questions I have about my project:
What do I need to put in my Guardfile to watch specific directories in my project for changes? I've several different ways which can be seen in my Guardfile as comments labelled like:
# Watch Specific Directory Attempt X
What is the difference between uncommenting lines 8 and 9 in my Guardfile (bellow Uncomment and set this to only include directories you want to watch) and adding "named group captures" like watch(%r{^lib/(?<path>.+)\.rb$}) { |m| "spec/lib/#{m[:path]}_spec.rb" } as described here
Where do I need to put the --clear option to make it persistent? I know I can run it with my binstub like bin/guard --clear and I've tried putting that in my Guardfile however it didn't work.
Are there any glaring convention, syntax, or clarity mistakes that you see in my project? I feel like I'm duck taping this whole thing together and I'd appreciate some guidance in piecing this thing together in a sensible way.
I'll answer the question in the title and cover the "sub-questions" as I go.
The best way to set up a project (as of now) is to use bundle exec guard --init rspec. This should give reasonable defaults to start work immediately. It's not perfect, but there is a lot of work planed to improve things, so do ask questions on GitHub instead (makes more sense).
Guard has to maintain backward compatibility, so there are some "non-intuitive" things for now and skimming through all the docs first (and wiki) is a good investment to quickly know what's available and where. Asking when confused or in doubt is also a good idea (one issue per question is best).
Guard uses a DSL to simplify setting up listeners. This is a bit non-intuitive and clunky at times, but it does help organize actions into groups, which can help maintain complex workflows. The DSL's command for e.g. clearing the terminal automatically is: (clearing: on). (This answers question 3).
There are all kinds of uses and scenarios, so Guard tries hard to make everyone happy and on every platform too. Guard uses Listen, which watches directories recursively (due to restrictions on OSX mostly). This usually isn't a problem, but for huge directions on OSX this can be very, very slow. That's why Guard lets you select which top directories to watch (like 'lib', 'app', etc.). Watching the whole project directory is very convenient, so that is still the default. More info on this is at the Listen project. So by default all directories (:directories statement) are "physically watched" (take up operating resources), though in Guard you only configure which changes you want to respond to (which is what watch statements do).
The words chosen are a bit misleading at times. E.g. watch in the DSL actually means: "out of all the changes happening, select changes matching ...". The block passed to watch is given the results of the match. That block should return a list of files for the current guard plugin to run. So "watch" probably is more misleading than helpful. "match" would probably be a better choice and it might replace "watch" in the future.
The guard-rspec project runs RSpec on changed files. You can see the exact RSpec commands if you run guard with the debugging option on, e.g. bundle exec guard -d. To simplify setup, Guard::RSpec uses a DSL that should work out-of-the-box if your project follows a given setup. E.g. dsl.watch_spec_files_for(ruby.lib_files) is defined here: so it pretty much already should do what you want if you put all your tested source files in lib. For other folders, you can add your own. E.g. Rails projects typically have sources also in an app directory, so in the default Guard::RSpec template there's an statement: dsl.watch_spec_files_for(rails.app_files) with the pattern defined as: rails.app_files = %r{^app/(.+)\.rb$} If you have a typical case that isn't covered, open an issue in that project. (covers question 2).
Everything looks fine in the example project and suggestions are mostly based on taste or preference. E.g.
Instead of let (:greeter) { Example::RSpecGreeter.new }, I'd use RSpec's implicit subject (but some may argue that it's less explicit and less readable)
if you're testing Example::RSpecGreeter, I'd recommend putting that class in a separate file and including it instead (require 'example/rspec_greeter')
you might add RubCop/Guard::RuboCop for detecting convention issues (covers 4th question)
you might want to check out Guard's own Guardfile used to test itself for a more "real-life" setup without the documentation clutter.
for best results I think it's best to copy a whole existing project and rename the parts you want to change. Usually there are many hours spent still fine-tuning things like alternate RSpec configs for Travis, special gem release tasks, certain workarounds and conveniences, etc.
Is there a tool for creating Ruby gem which automatically generate not only project file structure, but also tests file structure (with default ruby assert tests or rspec)?
You may want to take a look at hoe, which allows you to write your own project templates in erb, amongst other goodies. See http://docs.seattlerb.org/hoe/
Personally I have found, despite looking for something like this initially, that bundle gem <gemname> and a quick reference to an earlier project is not all that much work in practice, considering the number of gems I have written (about 7, though only one is published). Boris Stitnicky's comment rings true for me as well - understanding why a particular structure works, and building it from scratch at least a couple of times is worth the time invested in gaining Ruby knowledge.
However, if my day job project involved creating many in-house gems, I'd probably be using hoe, or a similar tool to get them started consistently.
Currently I am writing a Ruby on Rails application, and I am using Gems, however sometimes I feel that Gems are not as flexible as I want them to be. To make them more flexible. Should I
Fork them on github, and customize it, but this still present the challenging of managing everything.
or
Strip and merge the code of the gem to the main application? This will allow further customization of the gem. This would be for situations where a Gem require another Gem's functionality.
or is there a better way of doing this?
Thanks
B
Choice A is the better answer for a number of reasons.
You get to merge in security updates, enhancements, and bug fixes easily.
Your changes may get merged into the core--in fact, consider if you could implement them in such a way as they live alongside the core functionality as options. If this happens, you have the ultimate win--nothing to maintain, and you can retire your fork.
Others can benefit from your changes.
Your project's footprint is kept smaller and focused by keeping the gem code isolated.
You'll have something to add to your Github "resume."
If its some kind if not so popular gem or "bicycle" from some previous studio or developer who started project(in my case).
I prefer deprecate this gem's and move code into project,
for example they have c***la-deploy - it's just wrapper to Capistrano 2 with own methods))) - I just delete it and rewrite on last Capistrano 3
Than that have own "CMS" c***la-cms where they wrap standard form_for or simple_form with name "twitter_form_for" ? - fist of all I start try to find gem who use this name, and than find in dependency gem's ...
Its take a lot of time for new developer involve in project - better move to standard rails methods/heplers
But anyway i understand for a what this studio do that - its just vendor lock and for client more hard to move out from them to another developers.
For example for startup its bad to use a lot of dependencies and if it's just simple website - dose not matter.
I just started learning Ruby coming from Java. In Java you would use packages for a bigger projects. Is there anything equivalent to that in Ruby? Or what is the best way to achieve a package like setting?
The way I'm doing it right now is 'load'ing all the needed class into my new Ruby file. Isn't there a way to tell my current Ruby class to use all other Ruby classes in the same folder?
Cheers,
Mike
There's three kinds of package loading in Ruby:
Explicitly loading a library with require
Implicitly loading a library using autoload
Importing a library with gem
The require method is the most direct and has the effect of loading in and executing that particular file. Since that file may go on to require others, as a matter of convenience, you may end up loading in quite a lot at once.
The autoload method declares a module that will be loaded if you reference a given symbol. This is a common method to avoid loading things that you don't need, but making them automatically available if you do. Most large libraries use this method of loading to avoid dumping every single class into memory at once.
The gem approach is a more formalized way of packaging up a library. Although it is uncommon for applications to be split up into one or more gems, it is possible and provides some advantages. There's no obligation to publish a gem as open-source, you can keep it private and distribute it through your own channels, either a private web site or git repository, for instance, or simply copy and install the .gem file as required.
That being said, if you want to make a library that automatically loads a bunch of things, you might take this approach:
# lib/example.rb
Dir.glob(File.expand_path('example/**/*.rb', File.dirname(__FILE__))).each do |file|
require file
end
This would load all the .rb files in lib/example when you call require 'example'.
You probably want to use require rather than load, since it should take care of circular references.
If you want to grab all the files in a given folder, that's easy enough:
Dir.foreach("lib"){|x| require x}
Your other option is to have a file that manually requires everything, and have your other files require that.
You should also look at wrapping the code in your libraries with a module block, to give them their own namespaces.
That said: rightly or wrongly, I tend to feel that this is the one area -- perhaps the only one -- where Ruby is less powerful than Python, say, or Java.
I understand your feeling. It's an ordinary problem you have to face when coming from another language like Java. I'd say try to study Ruby modules but you deserve a longer reply. So my advice is reading a good Ruby book like Eloquent Ruby.
What are some of the best practices for OOD with Ruby? Mainly, how should files and code be organized?
I have a project that uses several classes and files and I am just wondering how it should all be organized, grouped and included.
It sounds like you're asking which pieces go in which files.
Is your project a Web application? In that case you would most likely use the system of organization imposed by your framework (Rails, Merb, Sinatra, etc.)
Other kinds of projects also have their own typical structure that you can just follow. E.g. gems are usually set up in a certain way.
If it's a console app, there's no strict rule. Usually people put no more than one class or module in a file. You could have one main file that requires all the others.
Standard OOD concepts apply to ruby. For specifics, maybe this guide will be helpful:
http://www.rubyist.net/~slagell/ruby/oothinking.html