Helping devs understand concerns faster

Apart from that, Betsy, what is the output on this whole topic? Is it something going to be done?

I think that your opinion of Concerns is a lot like mine, but Rails is a big tent and a lot of folks have very different opinions – just read this thread. So I think what’s to be “done” is for you to make as strong an argument as you can for your perspective in blog posts and the like.

2 Likes

I feel a lot of people are looking for help with handling complexity and growth at the domain model layer. Some of the techniques that come to mind are:

  • Extract model logic into specialised POROs
  • Extract model logic into a service layer
  • Separate large models into compositions of smaller modules (by functionality / identity)
  • Extract reusable aspects of models into separate mixins
  • Identify and extract domain concepts into new models
  • Separate the model layer into different bounded contexts

These are software design techniques, not Rails or even Ruby specific. Prescribing which techniques to use is a divisive topic. How to implement a given technique is also subject to individual preference and style.

Perhaps it’d be helpful to have documentation illustrating:

  • Selected techniques and a sample implementation using modules / concerns
  • Directory structure convention in a Rails codebase for said implementation
2 Likes

I completely agree. My point is that Rails is creating for us the concerns folder but it’s not the services or other folders suggesting structure/design patterns/whatever.

I don’t like to be insistent but I’ll try to make clear my point one last time (I promise :smile:). I think the output of this topic should be either:

  1. Rails stays accountable for the concerns folders created by default when running rails new and adds documentation on why are they creating them, thus avoiding confusion

OR

  1. Rails removes the creation of concerns folders by default when running rails new, thus avoiding confusion

@santib Thanks for those concrete suggestions!

Would you feel comfortable adding the documentaiton you proposed?

1 Like

Sure, I can give it a try. Though, it’d be good to have a validation from the Rails Core team beforehand, to prevent working on something that is not going to be accepted.

BTW, I just found this Documentation: a Rails guide for concerns by maryammouse · Pull Request #21114 · rails/rails · GitHub where they clearly express that they don’t want a specific guide for concerns, but they are willing to accept a PR explaining the concerns folders in the project structure documentation. Is that project structure documentation this one Getting Started with Rails — Ruby on Rails Guides ?

I’ll ask maryammouse if she is interested on doing this work before doing anything myself, she deserves it after what happened in the referenced PR :disappointed:

2 Likes

As someone who’s an enthusiastic user of concerns (and concerning! :sweat_smile:), I’d love to pitch in a few explainers.

What would help me would be to underline questions that people have in their mind when it comes to concerns or the problems solved with them. (And as someone with a limited working memory, questions also help me focus and not get lost when writing!)

I’ll try to collect a few question-answers on the side over time to make some kind of blog post with, and I’ll be happy to contribute anything deemed useful towards the official documentation.

2 Likes

Hey all! @santib forwarded me here from my PR on this documentation. It’s great to see this discussed! I’m ready to go add the docs I wrote (with any amendments of course) to the right place, but I haven’t been sure about where exactly that is (“project structure documentation” is all I had to go on - that might be in a pretty obvious place, but I couldn’t find any particular page that this description would apply to. My guess was that it might not be in the Rails guides, but if it was, then I think the Getting Started page seems like the one that best fits the description. Could I get confirmation that this would be the right place? :slight_smile:

2 Likes

Hi @maryammouse. Maybe it could be added to both the controllers guides and the activerecord or activemodel guides?

Ooof, that old PR thread is painful to read. :confounded: I find the whole “concerns” versus “service objects” debate to be rather maddening since the former simply doesn’t get documented/explained adequately and thus a lot of Rails n00bs gets persuaded by blogger noise from the latter perspective.

The mere fact that watching DHH’s Writing Software Well series and the concerns Basecamp used was a revelation for so many people is indication that the documentation has been sorely lacking. I don’t have a thumb big enough to thumbs up this improvement! :+1::+1::+1:

Edit: posts like this one (referenced above) are a perfect example…it just says Mixins are bad, don’t do it! Scary! Scary! …and provides absolutely no examples of what bad things might happen. I find code-free arguments over design patterns throughly unpersuasive.

6 Likes

@petrik Hmm, if it goes into the ActionController guide and the ActiveRecord guide (Action Controller Overview — Ruby on Rails Guides and (Active Record Basics — Ruby on Rails Guides for convenience) - Should each guide have it’s own small “concerns” section? That seems like the most logical fit to me; there isn’t a clear spot for concerns in the sections that currently exist.

If we want to use existing sections, the ActionController Methods and Actions section could work, as well as the ActiveRecord’s Convention Over Configuration section. What do you all think?

Also, what is the etiquette around tagging folks here - I second @santib’s desire for some validation from the Rails Core Team (or someone who can give reassurance) that the new location for the docs is approved before I go ahead and make the PR, though I will likely make the PR ahead of any approval anyway :sweat_smile:

2 Likes

@Betsy_Haibel Hope I’m not being a bother! :slight_smile: What do you think of the proposal around where to write the docs? I haven’t heard back from the Rails core team yet; do you know of a good way to reach out to them? How long does it typically take to hear back from them?

3 Likes

I’m not sure we agreed we need to document this. I still think concerns are regular Ruby modules and should not be documented on the Rails guides. We already have documentation of the API website about ActiveSupport::Concern with examples.

Although I think it would be good to showcase the feature in the Getting Started guide, so I’m not opposed to that. I’m so sure sure about adding a section on other guides or even creating a own guide for it.

Can we start showing case the Concerns on the Getting Started guide? Depending on the size of that section an the level of details that still need to be documented we may decide to move it.

2 Likes

Thanks for your feedback here! I’m really grateful to see it! I think showcasing Concerns in Getting Started is a great idea and a good start even if we decide to move it later. I’ll add the section in there in a documentation PR as soon as I can, should be the next week or two.

Edit: I also just wanted to add that I do think the documentation would be valuable to have within the Rails guides themselves and not just in the API website (whether we put it in Getting Started or elsewhere in the guides later). The reason I say this is because something I did not expect when I wrote my original PR years ago is that quite a lot of people commented on it over the years wondering why the documentation was not in the Guides already, and it seems like it became a “go-to” for people just learning about Rails and concerns. It seems to me that if the purpose of concerns was clear enough already, nobody would keep asking this question (in fact, this Discourse thread started independently of my PR and reflects the same issue). The API website only tells you the how, but not the why, so it doesn’t actually answer questions about what the actual folder is there for, what is the paradigm behind it, etc. I think this indicates a “hole” in the documentation, so I definitely advocate for filling it. :slight_smile:

2 Likes

I personally feel the docs need to be extended to add further stuff than just guides. It seems like there are lots of new rails users and existing users that find other stuff useful (like concerns), which don’t fit nicely into the guides.

E.g.

  • FAQs
  • folder structure breakdown (we do have a brief section on this already IIRC)
  • turorials
  • videos?

NOTE: I really like redwoodjs, they seem to have done a good job.

3 Likes

To add to the discussion

Having just app/models, app/controllers, app/views, app/helpers and lib is great. There are no app/models/services, app/models/entities, app/models/foos and in different projects and stages you can use different concepts. But we all know in our team that “business logic is in app/models”

But then there are concerns which “are just mixins added to autoload paths and some syntax sugar”. We’ve used concerns successfully when it comes to Picturable, Previewable, Permalinkable, but we’ve failed with others that should have been just POROs. - like we have a concern that is HasReputation, UserWithData.

The things I have experience to be difficult and I’ve been helping every member of our team with them and are not easily understood from documentation and guides are

  1. “What do you get by extending ActiveSupport::Concern?”
  2. “Why is there a different name in rails for a mixins?”
  3. “When are we using concerns”

It kind of feels they are central to rails as a new rails.project is created with two concerns folders, but it is not clear how central.

In addition to all the other good suggestions In the thread what I think would help many is a place pointing just that “concerns are just mixins with sugar syntax and you need it because…”

3 Likes

To keep myself accountable I wanted to say I started work on this today and have pushed up my work in progress for those who are curious: Comparing rails:master...maryammouse:maryammouse-concerns-docs · rails/rails · GitHub

It’s definitely not finished yet, but once it is ready for reviews, I will post here again and I look forward to seeing feedback at that time!

5 Likes

Hey all! Here is the PR ready for review! Add Concerns section in Refactoring portion of Getting Started guide by maryammouse · Pull Request #39766 · rails/rails · GitHub

I would love to get everyone’s comments and feedback. :slight_smile: I know a lot of good points were raised here regarding concerns; in my PR I’ve tried to add a fitting addition to the Getting Started guide, so I might not be able to address everything (I’ve been a bit concerned about the length), but I would like to do what I can, so please do let me know what you think.

7 Likes

Bringing in depth guides on using concerns in rails might lead to too much premature optimization for newcomers. The evidence I see already - many people in this thread didn’t even know they existed, but they’re clearly getting by without them. I’d be far more interested in a guide on the invented language (writing style) of concerns. How to identify when something is “able” (authenticable, eventable, etc. in DHH example) and what that might mean as far as writing style goes.

2 Likes

I agree that we don’t want to go too far into the weeds in a beginner’s guide, but from my experience, newcomers are confused by the unexplained presence of the folders, so I think that having a guide that explains how you would use them and why is important. If we don’t think beginners should use concerns, perhaps these folders should not be generated by default, or at least not generated in folders that a newcomer will definitely interact with. I think that ship has probably sailed…However, I’d also like to learn more about the invented language/style of concerns, though that seems like it would be more useful/interesting for more advanced Rails users than for beginners. :slight_smile:

4 Likes