understanding rails project

rubyonrails-talk
1

For me to understand the rails project is not enough to see the model or controller diagrams and how many attributes and actions they're having. I understand more if I know where actions are initialized and how they ended. To describe my thoughts more specifically I'll show some example. Let's take nice open project Railscasts. I chose the Comment controller because it nested inside others controllers then it's a little harder to understand how this works. Here's my picture that helps me to understand it. See diagram in attachment This isn't well composed diagram but fine for me. On this picture you can see where action is started and what's the reaction on action. The action edit initiates in views/episodes/show.html.erb, comes to controller's action edit, after that shows the edit form, then go to update action and finally go back to show.html.erb. From this picture you can see that a lot of actions initiate in show.html.erb that belongs to episode controller and makes harder to understand how works the comments controller. Now you can easy find place where is action comes.

Here is my questions:

Do you think this idea is useful for you, can make your developer's life easier ?

Do you know some tool that can make such kind of pictures automatically ?

Attachments: http://www.ruby-forum.com/attachment/5882/Comments.png

2

The 10/02/11, Megas Megas wrote:

This isn't well composed diagram but fine for me. On this picture you can see where action is started and what's the reaction on action. The action edit initiates in views/episodes/show.html.erb, comes to controller's action edit, after that shows the edit form, then go to update action and finally go back to show.html.erb. From this picture you can see that a lot of actions initiate in show.html.erb that belongs to episode controller and makes harder to understand how works the comments controller. Now you can easy find place where is action comes.

Here is my questions:

Do you think this idea is useful for you, can make your developer's life easier ?

This wouldn't be useless, at least. Providing graphic view of code sources is something already existing for some languages. These tools help for understanding, simplifying and designing software.

Do you know some tool that can make such kind of pictures automatically ?

No, I couldn't find any such tool for ruby.

If I had to start to write one, I would possibly start off of http://raa.ruby-lang.org/project/dia2code-ruby/ (GPL) which does the opposite thing (write code from a dia diagram).

3

For me - no, it's not useful. By following the conventions of Rails, I *know* how the application flows, and the file structure supports this. I also try to write "self-documenting" code - if some piece of code is so complex that it needs supporting documentation (flowcharts, images, etc), then that's a clue to me that it might well need refactoring to make it simpler to understand (I'm not talking about space shuttle operating systems here... I'm talking about bread-and-butter Rails web apps).

I *do* like to have object relationship diagrams to hand, though. As I find it quicker to look at associates on a single piece of paper, than by flipping from one model file to another. I have always used Railroad to generate them, although RubyMine IDE does have some dynamic model diagram generation built in.

4

To Michael Pavling I understood your point and let me check your statement by my questions.

How do you know which partition is using now? On my diagram at one glance i can see all partitions for current view. Sometimes some projects change layouts dynamically, I've spent a lot of time to discover this.

How do you find the place where action is initiated? Through the search? It takes a long time, isn't?

From the place where action is initiated, could be many chained/nested actions. How you can understand that one action will force some reaction and another reaction won't? Yes, you can do this in your mind but I found it is very long term activity.

When i made this diagram, everything in this controller became clear for me, but here's drawback - it takes a lot of time to build.

5

Megas Megas wrote in post #980942:

To Michael Pavling I understood your point and let me check your statement by my questions.

How do you know which partition is using now? On my diagram at one glance i can see all partitions for current view. Sometimes some projects change layouts dynamically, I've spent a lot of time to discover this.

The flow through a Rails application can be represented in Cucumber stories and be rediscovered by reading the stories that specify the behavior of the application. In my mind this is more useful than a bunch of compiled documentation that may or may not accurately represent the application at any given time.

Besides the automatic documentation provided by Cucumber stories the stories can be executed at any time to prove the application flow is as specified by the stories and that nothing has changed.

How do you find the place where action is initiated? Through the search? It takes a long time, isn't?

By reading the corresponding Cucumber story.

From the place where action is initiated, could be many chained/nested actions. How you can understand that one action will force some reaction and another reaction won't? Yes, you can do this in your mind but I found it is very long term activity.

I don't find this generally true in the Rails applications I've written to date. It's usually pretty obvious what's happening by reading the stories and unit tests.

When i made this diagram, everything in this controller became clear for me, but here's drawback - it takes a lot of time to build.

Spend that time writing Cucumber stories and specs with Rspec or unit tests with Test::Unit. Unlike diagrams the tests themselves can be executed to prove the behavior of the application code.

6

How do you know which partition is using now? On my diagram at one glance i can see all partitions for current view. Sometimes some projects change layouts dynamically, I've spent a lot of time to discover this.

(Partial, I assume). Yes, a little searching... but the context-sensitive control-clicking in my IDE lets me follow through very quickly, and I generally try to name stuff to be simple to find again (the self-documenting approach)

How do you find the place where action is initiated? Through the search? It takes a long time, isn't?

I don't know what you mean for sure. What "place"? Do you mean "controller action"? If so, I look at the URL... and I can open any file by name with a couple of key-presses.

When i made this diagram, everything in this controller became clear for me,

That's great to hear. I hope it works well for you. I'm all for people working in whatever way is best for them. For me; it's not so much help to have the controller/view drawing.

but here's drawback - it takes a lot of time to build.

But if the time it takes to build is off-sets in time you save from your previous searching, then it's a win.

But I would say that if others can find it quicker and easier while not using the drawing, then maybe the problem you're fixing with the diagram isn't the biggest win you could achieve?

7

Michael Pavling wrote in post #980954:

(Partial, I assume). Yes, a little searching... but the context-sensitive control-clicking in my IDE lets me follow through very quickly, and I generally try to name stuff to be simple to find again (the self-documenting approach)

Yes, you're right, partial In my IDE (RubyMine) some partial can't be reached by clicking, i assumed that if the good IDE can't do this job so another IDE's do worse job. I think that self-documented approach helps read the code locally, but to build the mind-image of the project is reading whole code many times. That's why the diagram tools were built, to help to create image of the project in mind. But all visual tools which I used are based on structure approach, no actions view. I think the action is very similar to goal, when I do the action it means I want to do something specifically: add new comment, create new account and etc. If I can see which controller, model, view are using now and where it comes from, while the current action is operating, then it helps me to understand the project.

I don't know what you mean for sure. What "place"? Do you mean "controller action"? If so, I look at the URL... and I can open any file by name with a couple of key-presses.

The place where is user click the action. In my example the comment views composed in another view, so this is not easy to find out what's going on.

That's great to hear. I hope it works well for you. I'm all for people working in whatever way is best for them. For me; it's not so much help to have the controller/view drawing. But if the time it takes to build is off-sets in time you save from your previous searching, then it's a win.

But I would say that if others can find it quicker and easier while not using the drawing, then maybe the problem you're fixing with the diagram isn't the biggest win you could achieve?

Actually I tried to describe one thing which have two sides and you separated it in two things. And you might be right, if Im not so good at Rails technology, it doesn't mean that others have the same problems. I think these difficulties appear only when we're reading the new someone else's project, not the our own project.