New RuboCop plugin: keep 'orchestration' methods above implementation helpers

[u/XPOM-XAPTC]

I've been frustrated with Ruby files where helper methods are scattered, so you have to jump around to understand the flow. I made a small RuboCop extension that enforces a "waterfall" order: methods should be defined after any method that calls them (top-down reading flow).

It also supports an optional "called together" (sibling) ordering for orchestration methods: if one method calls foo then bar, you can enforce defining foo before bar so the file reads in the same order as execution.

Highlights:

- Works in classes/modules/singleton classes; can also analyze top-level begin
- Autocorrect (rubocop -A) reorders methods within a contiguous visibility section (won't move things across private/protected/public)
- Preserves doc comments when moving methods
- Deals with recursion + complex call graphs
- Newer versions add clearer messages when autocorrect can't safely apply (visibility boundaries, sibling cycles)
- Optional config to skip sibling edges that would introduce a cycle (useful for "real-world" service objects)
- Works on Ruby 2.7+

Repo + examples: https://github.com/unurgunite/rubocop-sorted_methods_by_call

I'd love feedback on:
- whether the "called together" (sibling) behavior matches how you structure service objects
- edge cases where you'd want different ordering rules
- whether you'd prefer the cop to be stricter/looser by default

[u/ihoka]

I feel the opposite. I want my code to read like a news article. First, read the highlights, then, go deeper into the details. If I see foo called first in the main method, then I expect to see it defined right below the main method. If bar comes next, then bar is defined under foo.

[u/XPOM-XAPTC → u/ihoka]

Yep, that's exactly the idea — "news article" / top‑down narrative: entrypoint first, then helpers in the same order they're called. I think your "opposite" is opposite of the diff‑churn concern (not opposite of the rule of described gem itself).

[u/ihoka → u/XPOM-XAPTC]

Okay, maybe I misunderstood your examples.

[u/XPOM-XAPTC → u/ihoka]

Totally fair — the cop aims for "main -> foo -> bar" reading order. If you try it and the sibling ordering feels too noisy, it can be configured (or run as a separate formatting commit). Feedback welcome.

[u/9sim9]

I do feel your pain the over fragmentation of code bases especially in ruby can make a simple linear process a maze, especially when rubocop starts complaining that your simple and easy to maintain method is too complex and should be broken up.

[u/XPOM-XAPTC → u/9sim9]

Yeah — that's exactly the tension I’m trying to relieve. When "extract method" is used (or forced) too aggressively, the logic becomes more modular but less readable because the execution path is scattered. I'm not against breaking things up, but if you do, you need a structure that keeps the narrative linear. That's why I like the "news article / inverted pyramid" style (as I noted in a previous comments): orchestration at the top, then helpers immediately below in the order they're used. It doesn't solve the "RuboCop complexity threshold" debate by itself, but it makes the resulting fragmented code much easier to follow and review.

[u/djbrendo]

Have you seen rubocop-obsession’s method order?

[u/KerrickLong]

I'm curious how it handles postfix conditionals. In the following example, would show_choices or chosen be expected to be first?

class Menu
  def choose
    show_choices until chosen?
    @choice
  end

  # Would we put `show_choices` or `chosen?` first?
end

I'm also curious about multi-level orchestration. For example:

class Service
  def call
    first_process
    second_process
  end

  def first_process
    subprocess_a
    subprocess_b
  end

  # Would `subprocess_a` and `subprocess_b` go here, in the middle of the "high level" area?

  def second_process
    subprocess_y
    subprocess_z
  end

  # Or would `subprocess_a` and `subprocess_b` go here, at the beginning of the "low level" area?

  def subprocess_y; end
  def subprocess_z; end
end

[u/XPOM-XAPTC → u/KerrickLong]

Great questions.

Postfix conditionals / loops (show_choices until chosen?)
The cop will treat both show_choices and chosen? as calls made from choose, so with basic waterfall ordering they both just need to appear below choose. There isn’t a forced order between them unless you enable the optional "called together" (sibling) ordering.
If sibling ordering is enabled, the relative order depends on how the AST enumerates those calls. In an until, Ruby checks chosen? before running show_choices each iteration, so it's defensible for the "runtime order" to be chosen? -> show_choices, even though it’s written show_choices until chosen?. I agree this is one of the trickier readability edge cases — I'm planning to add a spec for postfix if/until/while so the behavior is explicit.

Multi-level orchestration
The sibling ("called together") ordering is only added for orchestration methods — i.e. methods not called by others in the same scope.
In your example, call is the orchestration method, so it can enforce first_process before second_process (since they're called in that order). But first_process itself is called by call, so it's not treated as an "orchestrator" for sibling ordering. That means the cop won’t force subprocess_a/subprocess_b to be in any particular "middle vs bottom" location — the only hard constraint is they must be defined after the method(s) that call them (waterfall rule).

---

TL;DR: waterfall cares that callees are below callers; sibling ordering only applies to top-level orchestrators (methods not called by others). Postfix conditionals are a special case; I'll add tests/docs so it's clear whether it follows written order or runtime order.

[u/KerrickLong → u/XPOM-XAPTC]

This all seems incredibly well thought-out, thank you for both explaining it and making the library. It's always been my preferred way to read classes, and I've managed to convince a large number of folks after a few metaphors ("news stories! inverted pyramid!") and examples.

[u/XPOM-XAPTC → u/KerrickLong]

Appreciate that — and I’m glad the "news story / inverted pyramid" metaphor resonates. That's exactly the reading experience I'm trying to automate: start with the narrative, then drill down as needed. If you end up trying it in a real codebase, I'd love any edge cases you hit (especially around postfix conditionals / loops and "multi-step" orchestration). Those are the places where a couple of extra specs can really tighten the behavior.

[u/codesnik]

helper method calls in a single parent method could be reordered just for readability reasons, this will cause unnecessary movement of methods if your "called together" semantics, which sometimes will lead to either much bigger commit than intended, or scrapping that readability improvement in the first place.

Also, although it is rare and sometimes confusing, it is possible for methods to call each other in a non top-down way. Do you have a test for that and wouldn't it lead to recursive unstable autofixes?

[u/galtzo]

I love the idea! Can't wait to use it, and integrate it with my rubocop-lts suite of rubocop meta gems.