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 or go to http://io.ua/17186846p
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
?
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
?
Do you think this idea is useful for you, can make your developer’s life
easier ?
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.
To Michael P.
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.
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?
(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.
To Michael P.
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.
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.