For a few years we've been slowly refactoring our controllers to use
"Resourceful Actions". I think it is worth having an issue here to explain the
process, so that other people know what's going on, and how they can help.
In Rails you can name your controller actions whatever you like. For example,
we have `go_public` in UsersController and `subscribe` in ChangesetsController.
Resourceful actions (sometimes known as "restful" actions, there's no strict
terminology here) are where a controller only has actions from the following
list:
* index
* show
* new
* create
* edit
* update
* destroy
This helps keep our code organised, and therefore easier to maintain. We can be
clear about which actions need database write access (create, update, destroy),
we know which actions will need a view template and which will iterate over a
list. This refactoring allows us to use more [resourceful
routing](https://guides.rubyonrails.org/routing.html#resource-routing-the-rails-default)
with fewer customisations.
When a controller has additional methods, that usually indicates that we need
(at least) one more controller. The first step is to consider what kind of
action you are looking at:
* Is it showing a list of items? It's probably an `index` action
* Is it showing just one item? It's probably a `show` action
* Is it creating something new? It's probably a `create` action
* etc
The tricky part is trying to find the right name for the new controller. Here's
my guidance, perhaps other people can help clarify further.
First, controllers should usually be named after nouns. The actions are verbs,
and those verbs should apply to a noun. So for example, with
ChangesetsController#subscribe, then instead of using the verb "subscribe" you
could use the verb "create" on the noun "subscription". (An alternative might
be to "create" a "subscriber", which is also a noun (and changesets do have
"subscribers"), but we aren't creating the user here so "creating" a
"subscriber" isn't quite accurate).
Secondly, you will likely then up with a chain of multiple nouns. So in our
example, we have a "subscription" noun and also the "changeset" noun, since we
are creating a subscription to the changeset. In general, if one of the nouns
is the same as a model, it will be the name of the module. So in
`app/controllers/changesets/subscriptions_controller.rb` we have
```
module Changesets
class SubscriptionsController < ApplicationController
```
(The alternative here would be to have a subscriptions module with various
controllers named after our models inside that, which could work, but is harder
to navigate for developers).
It's worth putting in time and effort to find the right names for the
controllers, which is usually trying to find the correct noun(s). This often
needs to be discussed with other developers, since [naming things is one of the
two hardest problems in computer
science](https://x.com/secretGeek/status/72699978680). For example it's not
obvious what the noun is for "go_public" in UsersController - perhaps we are
"updating" the "PublicStatus" of the "User"? Or something else?
The other problem is that in English, many nouns can also be used as verbs.
"mark", "export", "embed" are examples where they are both verbs and nouns in
our context ("feed" and "mine" are also verbs in other contexts!). So sometimes
you might find that the action is the same or similar to a noun, but perhaps
there is a better noun that makes things clearer. Again, please feel free to
ask.
If you have any questions or uncertainties about this process, then I'm happy
to clarify.
--
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/5539
You are receiving this because you are subscribed to this thread.
Message ID: <openstreetmap/openstreetmap-website/issues/5...@github.com>_______________________________________________
rails-dev mailing list
rails-dev@openstreetmap.org
https://lists.openstreetmap.org/listinfo/rails-dev
