Erlang Module Export vs. Private Functions: Avoiding Accidental Public Access

Direct Answer

To keep helper predicates truly private while still enjoying -export_all for quick experiments, never ship code compiled with -export_all. Use explicit -export lists in production, and constrain -export_all to interactive sessions or temporary build directories. Combine this with a naming convention (e.g., prefix helpers with _) and a lint rule that flags any exported function matching that prefix when -export_all is active.

Confirmed Facts

• Functions not in -export are inaccessible from other modules at runtime; the rule is enforced by the BEAM VM, not just a convention.
• The compiler option +export_all (or {export_all,true} in rebar.config) overrides any explicit -export list, making every function public.
• When a name appears in -export but no matching clause exists, the compiler emits a warning: warning: function X/Y is not defined. This does not stop beam generation.
• Dialyzer and xref can surface unintended exports: Dialyzer reports functions that are exported but never called externally, and xref can be invoked with the exports flag for a similar scan.
• Best practice is to forbid -export_all in production builds. CI pipelines can enforce explicit export lists via compiler flags or lint plugins.

Likely Explanation

Because Erlang allows dynamic calls (apply/3, spawn/3 with a module/fun/arity tuple), the language designers opted for a simple visibility model: a function is either exported or not. Adding a formal -private attribute would break backward compatibility—existing modules that rely on -export_all would suddenly hide functions, breaking callers that depend on the current all‑public behavior. Therefore, visibility control remains at the module‑attribute level.

Practical Steps for This Case

1. Adopt explicit export lists. Declare only the public API in -export([Public/Arity, ...]) and omit helper functions.
2. Scope -export_all to prototyping. Use it only in an interactive shell (erl -compile(export_all)) or a temporary build directory. Do not commit or ship beam files compiled with this flag.
3. Use a private naming convention. Prefix helper functions with an underscore (e.g., _helper/1). This makes accidental export obvious.
4. Enforce rules in CI. Add a lint step with rebar3_lint or elvis that:
   • forbids -export_all in production profiles, and
   • flags exported functions whose names start with _ when -export_all is active.
5. Run static analysis. Execute dialyzer --src -r src/ and look for messages such as Function ... is exported but never used externally to surface over‑exposed functions.
6. Verify compiler warnings. Compile a module with an undefined export and confirm the warning appears.

Verification Commands (Safe, Scoped)

# 1. Confirm warning for undefined export
cat > test.erl <<EOF
-module(test). -export([foo/0, bar/0]). foo() -> ok.
EOF

erlc -W test.erl
# Expected: warning: function bar/0 is not defined

# 2. Verify -export_all makes an undefined function callable
cat > test2.erl <<EOF
-module(test2). -export([foo/0]). foo() -> ok.
EOF

erlc +export_all test2.erl
erl -noshell -eval 'test2:foo().' -s init stop
# foo/0 works; if bar/0 existed it would be callable too

# 3. Run Dialyzer to detect over‑exported helpers
# (Assumes a project in src/)
dialyzer --src -r src/ 2>&1 | grep "exported but never used externally"

# 4. Example rebar3_lint rule to forbid -export_all in prod
# In rebar.config:
# {rebar3_lint, [
#   {profiles, [prod]},
#   {rules, [
#     {forbid_export_all, []},
#     {exported_private_prefix, ["_"]}
#   ]}
# ]}.

Missing Diagnostic Detail

Which build tool and OTP version are you using (e.g., rebar3 3.22, OTP 26.2)? This determines which lint plugins and compiler options are available and whether xref integration is straightforward.