[erlang-questions] Some functions must return values other may do so...

Joe Armstrong erlang@REDACTED
Sat Aug 15 16:56:37 CEST 2015

For a while now I've adopted a convention for naming functions
which I find rather useful, so I thought I'd discuss it here,
(it's a kind of RFC-2119 lite notation :-)

Rule1: Functions which return {ok,X} | {error,W} are called may_<name>

Rule2: Functions which return a value or raise an exception are called

I use a small interface library which enforced this, for example,
I have a wrapper round file:open which looks like this:

   must_open_file(File, Mode) ->
       case file:open(File, Mode) of
           {ok, X} ->
           {error, E} ->

   may_open_file(File, Mode) ->
      file:open(File, Mode).

Using this convention

  dict:find(Key, D)  should be called may_get(Key, Dict)
  dict:fetch(Key, D) should be renames must_get(Key, Dict)

With this convention I can write code like:

   must_sequence() ->
      Handle = must_open_file("some_file_which_i_know_must_exist.txt", [read]),
      Data = must_read_file(Handle),
      must_write_file("fileout", Data).

Or, when "file" might exist, I'd write:

    test1() ->
        case may_open_file("file", [read]) of
           {ok, Handle} ->
           {error, _} ->
                 .. do something else ...

may_<name> function are *always* called from case statements
must_<name> function are called in linear code with no case statements

I usually also wrap the top level call to a sequence of
must_* functions in a catch, something like:

     top() ->
         case (catch must_sequence()) of
             {'EXIT', What} ->
                ... do some recovery stuff ...
             Ok ->

Code written using the must/may convention seems to be extremely easy
to read, since from the name of the function I don't have to speculate
to the form of the return value - I know immediately if the function
will raise and exception on error or give an ok/error return value.



More information about the erlang-questions mailing list