Doctests for private functions

I have the following module where as I developed the code I was using doctests to verify if the function did what I expected. The problem is these doctests that I was writing are for functions that eventually became private functions:

  • Removing the doctests for the private functions does not help here as I need the tests — they help with catching regressions and help document the functionality of the code. Without these tests, it may not be clear to someone reading the code what exactly the private function does.

  • I could move the code inside the public function but that results in a big monolithic function and the separate functions help clarify the logic.

What is the recommended way to reconcile this in Elixir? (I seem to run into this problem very often — requiring doctests for private functions, that is)

The only solution I know is to create a separate Impl module and move the private functions as public functions like @pragdave describes here: https://pragdave.me/blog/2017/07/13/decoupling-interface-and-implementation-in-elixir.html . Is this an anti-pattern (given that I would be effectively “exposing” the private functions in a way)? I love this approach, but I was wondering if there was another way to have doctests for private functions — I would presume this would be a common problem?

What is the guidance here? Also, is there a way to remove these warnings for @docs on private functions?

defmodule InverseCaptcha do
  @moduledoc """
  Solves the Inverse Captcha problem.
  http://adventofcode.com/2017/day/1

  Run with:

      mix
      ./inverse_captcha 1122
  """

  def solve_captcha(string) do
    string
    |> string_to_list
    |> sum_of_digits_matching_next
  end

  @doc """
      iex> string_to_list("1122")
      [1, 1, 2, 2]
  """
  defp string_to_list(string) do
    string
    |> String.splitter("", trim: true)
    |> Stream.map(& String.to_integer(&1))
    |> Enum.to_list
  end

  @doc """
  ## Examples

      iex> sum_of_digits_matching_next([1, 1, 2, 2])
      3

      iex> sum_of_digits_matching_next([1, 1, 1, 1])
      4

      iex> sum_of_digits_matching_next([1, 2, 3, 4])
      0

      iex> sum_of_digits_matching_next([9, 1, 2, 1, 2, 1, 2, 9])
      9
  """
  defp sum_of_digits_matching_next(list) do
    list_with_head = (list ++ [hd(list)])

    list_with_head
    |> Enum.zip(tl(list_with_head))
    |> Enum.reduce(0, fn {x, y}, acc ->
         if x == y do
           x + acc
         else
           acc
         end
       end)
  end
end

defmodule InverseCaptcha.CLI do
  def main(args) do
    string = hd(args)
    IO.puts InverseCaptcha.solve_captcha(string)
  end
end

Private functions are not meant to get tested at all, not per unit test not per doctest. Also private functions are not meant to be documented.

The compiler spits out a warning when you try it. You can remove that warning by removing the documentation.

And last but not least, a doctest is not to verify that the function works as expected, but they are to verify that the examples in your documentation are correct.

There have been some discussions around this on the old mailinglist, on the core mailinglist, and on this forum as well.

Why wouldn’t you want to unit test a private function? I can more or less understand not documenting it given that they are not meant to be exposed- but unit testing?

I consider private functions just as “implementation details”, so I focus on testing only the module’s public APIs. On the other hand, if your public functions are working as expected, I think you can happily assume that your private functions are working aswell.

About documenting private methods, I understand the reasons to not doing so. But to be honest, I find this documentation useful for other developers contributing to the project.

1 Like

Sometimes I’ve seen a tendency in my own code for private functions to grow a bit too complex; I usually take that as a hint that maybe they should be public functions in some kind of utility module or similar.

My idea of a “good” private function is mostly along the lines of a one-liner to shorten, and give a proper name to, a part of a larger transformation / pipe sequence.

If it gets more complex, like mapping a set of values to something else, etc, then I definitely feel it should be a public function, either in the current module or another one that fits better.

2 Likes

Private functions have different semantics than public ones, what Jose explained here quite well: Proposal: @docp for private function documentation and doctests