<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>Naming Conventions – Elixir v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/elixir/v1.7/naming-conventions.html" />
<script src="dist/sidebar_items-cdf4e58b19.js"></script>
</head>
<body data-type="extras">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
Elixir </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="Elixir" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
<li><a id="exceptions-list" href="#full-list">Exceptions</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>Naming Conventions</h1>
<p>This document covers some naming conventions in Elixir code, from casing to punctuation characters.</p>
<h2 id="casing" class="section-heading">
<a href="#casing" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Casing
</h2>
<p>Elixir developers must use <code class="inline">snake_case</code> when defining variables, function names, module attributes, etc:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">some_map</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="3769080023-1">%{</span><span class="ss">this_is_a_key</span><span class="p">:</span><span class="w"> </span><span class="s">"and a value"</span><span class="p" data-group-id="3769080023-1">}</span><span class="w">
</span><span class="n">is_map</span><span class="p" data-group-id="3769080023-2">(</span><span class="n">some_map</span><span class="p" data-group-id="3769080023-2">)</span></code></pre>
<p>Aliases, commonly used as module names, are an exception as they must be capitalized and written in <code class="inline">CamelCase</code>, like <a href="OptionParser.html"><code class="inline">OptionParser</code></a>. For aliases, capital letters are kept in acronyms, like <code class="inline">ExUnit.CaptureIO</code> or <code class="inline">Mix.SCM</code>.</p>
<p>Atoms can be written either in <code class="inline">:snake_case</code> or <code class="inline">:CamelCase</code>, although the convention is to use the snake case version throughout Elixir.</p>
<p>Generally speaking, filenames follow the <code class="inline">snake_case</code> convention of the module they define. For example, <code class="inline">MyApp</code> should be defined inside the <code class="inline">my_app.ex</code> file. However, this is only a convention. At the end of the day, any filename can be used as they do not affect the compiled code in any way.</p>
<h2 id="underscore-_foo" class="section-heading">
<a href="#underscore-_foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Underscore (<code class="inline">_foo</code>)
</h2>
<p>Elixir relies on underscores in different situations.</p>
<p>For example, a value that is not meant to be used must be assigned to <code class="inline">_</code> or to a variable starting with underscore:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="p" data-group-id="5941523229-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="c">_contents</span><span class="p" data-group-id="5941523229-1">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">File</span><span class="o">.</span><span class="n">read</span><span class="p" data-group-id="5941523229-2">(</span><span class="s">"README.md"</span><span class="p" data-group-id="5941523229-2">)</span></code></pre>
<p>Function names may also start with an underscore. Such functions are never imported by default:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Example</span><span class="w"> </span><span class="k" data-group-id="9015467229-1">do</span><span class="w">
</span><span class="gp unselectable">...> </span><span class="w"> </span><span class="kd">def</span><span class="w"> </span><span class="nf">_wont_be_imported</span><span class="w"> </span><span class="k" data-group-id="9015467229-2">do</span><span class="w">
</span><span class="gp unselectable">...> </span><span class="w"> </span><span class="ss">:oops</span><span class="w">
</span><span class="gp unselectable">...> </span><span class="w"> </span><span class="k" data-group-id="9015467229-2">end</span><span class="w">
</span><span class="gp unselectable">...> </span><span class="k" data-group-id="9015467229-1">end</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="kn">import</span><span class="w"> </span><span class="nc">Example</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="c">_wont_be_imported</span><span class="p" data-group-id="9015467229-3">(</span><span class="p" data-group-id="9015467229-3">)</span><span class="w">
</span><span class="gt">** (CompileError) iex:1: undefined function _wont_be_imported/0</span></code></pre>
<p>Due to this property, Elixir relies on functions starting with underscore to attach compile-time metadata to modules. Such functions are most often in the <code class="inline">__foo__</code> format. For example, every module in Elixir has an <code class="inline">__info__/1</code> function:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="nc">String</span><span class="o">.</span><span class="c">__info__</span><span class="p" data-group-id="2938614223-1">(</span><span class="ss">:functions</span><span class="p" data-group-id="2938614223-1">)</span><span class="w">
</span><span class="p" data-group-id="2938614223-2">[</span><span class="ss">at</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="ss">capitalize</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="ss">chunk</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">...</span><span class="p" data-group-id="2938614223-2">]</span></code></pre>
<p>Elixir also includes five special forms that follow the double underscore format: <a href="Kernel.SpecialForms.html#__CALLER__/0"><code class="inline">__CALLER__/0</code></a>, <a href="Kernel.SpecialForms.html#__DIR__/0"><code class="inline">__DIR__/0</code></a>, <a href="Kernel.SpecialForms.html#__ENV__/0"><code class="inline">__ENV__/0</code></a>and <a href="Kernel.SpecialForms.html#__MODULE__/0"><code class="inline">__MODULE__/0</code></a> retrieve compile-time information about the current environment, while <a href="Kernel.SpecialForms.html#__STACKTRACE__/0"><code class="inline">__STACKTRACE__/0</code></a> retrieves the stacktrace for the current exception.</p>
<h2 id="trailing-bang-foo" class="section-heading">
<a href="#trailing-bang-foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Trailing bang (<code class="inline">foo!</code>)
</h2>
<p>A trailing bang (exclamation mark) signifies a function or macro where failure cases raise an exception.</p>
<p>Many functions come in pairs, such as <a href="File.html#read/1"><code class="inline">File.read/1</code></a> and <a href="File.html#read!/1"><code class="inline">File.read!/1</code></a>. <a href="File.html#read/1"><code class="inline">File.read/1</code></a> will return a success or failure tuple, whereas <a href="File.html#read!/1"><code class="inline">File.read!/1</code></a> will return a plain value or else raise an exception:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex> </span><span class="nc">File</span><span class="o">.</span><span class="n">read</span><span class="p" data-group-id="9979488511-1">(</span><span class="s">"file.txt"</span><span class="p" data-group-id="9979488511-1">)</span><span class="w">
</span><span class="p" data-group-id="9979488511-2">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="s">"file contents"</span><span class="p" data-group-id="9979488511-2">}</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">File</span><span class="o">.</span><span class="n">read</span><span class="p" data-group-id="9979488511-3">(</span><span class="s">"no_such_file.txt"</span><span class="p" data-group-id="9979488511-3">)</span><span class="w">
</span><span class="p" data-group-id="9979488511-4">{</span><span class="ss">:error</span><span class="p">,</span><span class="w"> </span><span class="ss">:enoent</span><span class="p" data-group-id="9979488511-4">}</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">File</span><span class="o">.</span><span class="n">read!</span><span class="p" data-group-id="9979488511-5">(</span><span class="s">"file.txt"</span><span class="p" data-group-id="9979488511-5">)</span><span class="w">
</span><span class="s">"file contents"</span><span class="w">
</span><span class="gp unselectable">iex> </span><span class="nc">File</span><span class="o">.</span><span class="n">read!</span><span class="p" data-group-id="9979488511-6">(</span><span class="s">"no_such_file.txt"</span><span class="p" data-group-id="9979488511-6">)</span><span class="w">
</span><span class="gt">** (File.Error) could not read file no_such_file.txt: no such file or directory</span></code></pre>
<p>The version without <code class="inline">!</code> is preferred when you want to handle different outcomes using pattern matching:</p>
<pre><code class="nohighlight makeup elixir"><span class="k">case</span><span class="w"> </span><span class="nc">File</span><span class="o">.</span><span class="n">read</span><span class="p" data-group-id="5327887614-1">(</span><span class="n">file</span><span class="p" data-group-id="5327887614-1">)</span><span class="w"> </span><span class="k" data-group-id="5327887614-2">do</span><span class="w">
</span><span class="p" data-group-id="5327887614-3">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">body</span><span class="p" data-group-id="5327887614-3">}</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="c1"># do something with the `body`</span><span class="w">
</span><span class="p" data-group-id="5327887614-4">{</span><span class="ss">:error</span><span class="p">,</span><span class="w"> </span><span class="n">reason</span><span class="p" data-group-id="5327887614-4">}</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="c1"># handle the error caused by `reason`</span><span class="w">
</span><span class="k" data-group-id="5327887614-2">end</span></code></pre>
<p>However, if you expect the outcome to always to be successful (e.g. if you expect the file always to exist), the bang variation can be more convenient and will raise a more helpful error message (than a failed pattern match) on failure.</p>
<p>More examples of paired functions: <a href="Base.html#decode16/2"><code class="inline">Base.decode16/2</code></a> and <a href="Base.html#decode16!/2"><code class="inline">Base.decode16!/2</code></a>, <a href="File.html#cwd/0"><code class="inline">File.cwd/0</code></a> and <a href="File.html#cwd!/0"><code class="inline">File.cwd!/0</code></a></p>
<p>There are also some non-paired functions, with no non-bang variant. The bang still signifies that it will raise an exception on failure. Examples: <code class="inline">Mix.Config.validate!/1</code>, <a href="Protocol.html#assert_protocol!/1"><code class="inline">Protocol.assert_protocol!/1</code></a></p>
<p>In macro code, the bang on <a href="Kernel.html#alias!/1"><code class="inline">Kernel.alias!/1</code></a> and <a href="Kernel.html#var!/2"><code class="inline">Kernel.var!/2</code></a> signifies that <a href="http://elixir-lang.org/getting-started/meta/macros.html#macros-hygiene">macro hygiene</a> is set aside.</p>
<h2 id="trailing-question-mark-foo" class="section-heading">
<a href="#trailing-question-mark-foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Trailing question mark (<code class="inline">foo?</code>)
</h2>
<p>Functions that return a boolean are named with a trailing question mark.</p>
<p>Examples: <a href="Keyword.html#keyword?/1"><code class="inline">Keyword.keyword?/1</code></a>, <code class="inline">Mix.debug?/0</code>, <a href="String.html#contains?/2"><code class="inline">String.contains?/2</code></a></p>
<p>However, functions that return booleans and are valid in guards follow another convention, described next.</p>
<h2 id="is_-prefix-is_foo" class="section-heading">
<a href="#is_-prefix-is_foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
<code class="inline">is_</code> prefix (<code class="inline">is_foo</code>)
</h2>
<p>Type checks and other boolean checks that are allowed in guard clauses are named with an <code class="inline">is_</code> prefix.</p>
<p>Examples: <a href="Integer.html#is_even/1"><code class="inline">Integer.is_even/1</code></a>, <a href="Kernel.html#is_list/1"><code class="inline">Kernel.is_list/1</code></a></p>
<p>These functions and macros follow the Erlang convention of an <code class="inline">is_</code> prefix, instead of a trailing question mark, precisely to indicate that they are allowed in guard clauses.</p>
<p>Note that type checks that are not valid in guard clauses do not follow this convention. Examples: <a href="Keyword.html#keyword?/1"><code class="inline">Keyword.keyword?/1</code></a>, <a href="Regex.html#regex?/1"><code class="inline">Regex.regex?/1</code></a></p>
<h2 id="special-names" class="section-heading">
<a href="#special-names" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Special names
</h2>
<p>Some names have specific meaning in Elixir. We detail those cases below.</p>
<h3 id="length-and-size" class="section-heading">
<a href="#length-and-size" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
length and size
</h3>
<p>When you see <code class="inline">size</code> in a function name, it means the operation runs in constant time (also written as “O(1) time”) because the size is stored alongside the data structure.</p>
<p>Examples: <a href="Kernel.html#map_size/1"><code class="inline">Kernel.map_size/1</code></a>, <a href="Kernel.html#tuple_size/1"><code class="inline">Kernel.tuple_size/1</code></a></p>
<p>When you see <code class="inline">length</code>, the operation runs in linear time (“O(n) time”) because the entire data structure has to be traversed.</p>
<p>Examples: <a href="Kernel.html#length/1"><code class="inline">Kernel.length/1</code></a>, <a href="String.html#length/1"><code class="inline">String.length/1</code></a></p>
<p>In other words, functions using the word “size” in its name will take the same amount of time whether the data structure is tiny or huge. Conversely, functions having “length” in its name will take more time as the data structure grows in size.</p>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
