emberjs/website — pull request #1848 by henrik (2014-11-29 23:47:29+00:00)
Title: naming-conventions: clarify resource/route rule

I wouldn't want this initial commit merged as-is – just a starting point for the discussion.

I find this quite unclear, and it also uses incorrect parts of speech:

> The rule of thumb is to use resources for nouns, and routes for
> adjectives (`favorites`) or verbs (`edit`). This ensures that
> nesting does not create ridiculously long names, but avoids
> collisions with common adjectives and verbs.

I'd be very happy to try and clarify this bit, but I first need help understanding what it's actually intended to say.

First, about the parts of speech:

While "favorite" *can* be an adjective ("my favorite thing"), "favorites" cannot. It's either a noun ("my favorites") or possibly a verb ("he favorites things"). It doesn't seem to be used like a verb here though, so I'd say it's a noun.

What I find unclear:

If it's not actually an adjective but a noun, then what is the actual rule of thumb here, that we want to recommend? Why should you use `routes` instead of `resources`? Is it because it's a subset/filter: `/posts/favorites` to filter all posts to show only the ones that are favorites? Whereas one would still use `resources` for `/users/123/favorites/456`?

Alternatively the example could be changed to `/posts/favorited` and then it *is* actually an adjective (or a verb/participle).

I also don't understand why this rule of thumb mean nesting doesn't create long names.

And I also don't understand in what sense it avoids collisions.

Again, I'd love to clarify this paragraph but I need help understanding it first :)