Thoughts on public/private function ordering about elixir_style_guide HOT 4 CLOSED

I prefer option # 2, keeping private functions proximate to the ones that use them (as you can observe in Ecto and the standard library), rather than strictly separating the module into public and private.

In a well-written module, the public functions will be easy to pick out from their @doc tags, while their private functions can be tucked below and kept accessible.

Any helper functions that are used by multiple functions can still be placed together at the end of the module rather than after whichever function first used them.

This module illustrates this nicely: https://github.com/elixir-lang/elixir/blob/030e0c7b53023ab2d75780dbdfe54c9cce225385/lib/elixir/lib/io/ansi/docs.ex

from elixir_style_guide.

@christopheradams Thanks for the reply, you make some good points. I think you're probably right in this case. Using @doc certainly draws attention to the public functions in a module, but I'll note that there is sometimes a difference here between @doc usage in internal vs external projects. On many of my Phoenix projects we don't use @docs for our context functions because they're only used internally and generally intuitively named. With libraries like Ecto and the elixir standard library, having @docs makes more sense since you have a wide audience of people using the libraries.

The module you linked to does give me some ideas though. Prefixing each public function with @spec would also make any module skimmable.

Is the ordering of public/private functions something we want to include in the styleguide? If so, I'm happy to take a crack at it.

from elixir_style_guide.

from elixir_style_guide.

There's no precedent at all for prefixing private functions with an underscore.

I don't think the guide can take a position on private function placement, such as saying that they should always be at the bottom of the module, or below the function that uses them.

from elixir_style_guide.