levovix
/
Nim
mirror of https://github.com/nim-lang/Nim


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Standard Library Style Guide</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">Standard Library Style Guide</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="introduction_toc" href="#introduction">Introduction</a></li>
<ul class="simple"><li><a class="reference" id="style-guidelines-spacing-and-whitespace-conventions_toc" href="#style-guidelines-spacing-and-whitespace-conventions">Spacing and Whitespace Conventions</a></li>
<li><a class="reference" id="style-guidelines-naming-conventions_toc" href="#style-guidelines-naming-conventions">Naming Conventions</a></li>
<li><a class="reference" id="style-guidelines-coding-conventions_toc" href="#style-guidelines-coding-conventions">Coding Conventions</a></li>
<li><a class="reference" id="style-guidelines-conventions-for-multiminusline-statements-and-expressions_toc" href="#style-guidelines-conventions-for-multiminusline-statements-and-expressions">Conventions for multi-line statements and expressions</a></li>
<li><a class="reference" id="style-guidelines-miscellaneous_toc" href="#style-guidelines-miscellaneous">Miscellaneous</a></li>
</ul>
</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/nep1.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/nep1.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Clay Sweetser, Dominik Picheta</td></tr>
<tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
</tbody></table>
<h1><a class="toc-backref" id="introduction" href="#introduction">Introduction</a></h1><p>Although Nim supports a variety of code and formatting styles, it is nevertheless beneficial that certain community efforts, such as the standard library, should follow a consistent set of style guidelines when suitable. This enhancement proposal aims to list a series of guidelines that the standard library should follow.</p>
<p>Note that there can be exceptions to these rules. Nim being as flexible as it is, there will be parts of this style guide that don't make sense in certain contexts. Furthermore, just as <a class="reference external" href="https://legacy.python.org/dev/peps/pep-0008/">Python's style guide</a> changes over time, this style guide will too.</p>
<p>These rules will only be enforced for contributions to the Nim codebase and official projects, such as the Nim compiler, the standard library, and the various official tools such as C2Nim.</p>
<h2 id="introduction-style-guidelines"><center>Style Guidelines</center></h2>
<h3><a class="toc-backref" id="style-guidelines-spacing-and-whitespace-conventions" href="#style-guidelines-spacing-and-whitespace-conventions">Spacing and Whitespace Conventions</a></h3><ul class="simple"><li>Lines should be no longer than 80 characters. Limiting the amount of information present on each line makes for more readable code - the reader has smaller chunks to process.</li>
<li>Two spaces should be used for indentation of blocks; tabstops are not allowed (the compiler enforces this). Using spaces means that the appearance of code is more consistent across editors. Unlike spaces, tabstop width varies across editors, and not all editors provide means of changing this width.</li>
<li><p>Although use of whitespace for stylistic reasons other than the ones endorsed by this guide are allowed, careful thought should be put into such practices. Not all editors support automatic alignment of code sections, and re-aligning long sections of code by hand can quickly become tedious.</p>
<p><pre class="listing"><span class="Comment"># This is bad, as the next time someone comes</span>
<span class="Comment"># to edit this code block, they</span>
<span class="Comment"># must re-align all the assignments again:</span>
<span class="Keyword">type</span>
  <span class="Identifier">WordBool</span><span class="Operator">*</span>    <span class="Operator">=</span> <span class="Identifier">int16</span>
  <span class="Identifier">CalType</span><span class="Operator">*</span>     <span class="Operator">=</span> <span class="Identifier">int</span>
  <span class="Operator">...</span> <span class="Comment"># 5 lines later</span>
  <span class="Identifier">CalId</span><span class="Operator">*</span>       <span class="Operator">=</span> <span class="Identifier">int</span>
  <span class="Identifier">LongLong</span><span class="Operator">*</span>    <span class="Operator">=</span> <span class="Identifier">int64</span>
  <span class="Identifier">LongLongPtr</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">ptr</span> <span class="Identifier">LongLong</span></pre></p>
</li>
</ul>

<h3><a class="toc-backref" id="style-guidelines-naming-conventions" href="#style-guidelines-naming-conventions">Naming Conventions</a></h3><ul class="simple"><li><p>Type identifiers should be in PascalCase. All other identifiers should be in camelCase with the exception of constants which <strong>may</strong> use PascalCase but are not required to.</p>
<p><pre class="listing"><span class="Comment"># Constants can start with either a lower case or upper case letter.</span>
<span class="Keyword">const</span> <span class="Identifier">aConstant</span> <span class="Operator">=</span> <span class="DecNumber">42</span>
<span class="Keyword">const</span> <span class="Identifier">FooBar</span> <span class="Operator">=</span> <span class="FloatNumber">4.2</span>

<span class="Keyword">var</span> <span class="Identifier">aVariable</span> <span class="Operator">=</span> <span class="StringLit">&quot;Meep&quot;</span> <span class="Comment"># Variables must start with a lowercase letter.</span>

<span class="Comment"># Types must start with an uppercase letter.</span>
<span class="Keyword">type</span>
  <span class="Identifier">FooBar</span> <span class="Operator">=</span> <span class="Keyword">object</span></pre></p>
<p>For constants coming from a C/C++ wrapper, ALL_UPPERCASE are allowed, but ugly. (Why shout CONSTANT? Constants do no harm, variables do!)</p>
</li>
<li><p>When naming types that come in value, pointer, and reference varieties, use a regular name for the variety that is to be used the most, and add a &quot;Obj&quot;, &quot;Ref&quot;, or &quot;Ptr&quot; suffix for the other varieties. If there is no single variety that will be used the most, add the suffixes to the pointer variants only. The same applies to C/C++ wrappers.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">Handle</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Comment"># Will be used most often</span>
    <span class="Identifier">fd</span><span class="Punctuation">:</span> <span class="Identifier">int64</span>
  <span class="Identifier">HandleRef</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Identifier">Handle</span> <span class="Comment"># Will be used less often</span></pre></p>
</li>
<li><p>Exception and Error types should have the &quot;Error&quot; or &quot;Defect&quot; suffix.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">ValueError</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">CatchableError</span>
  <span class="Identifier">AssertionDefect</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Defect</span>
  <span class="Identifier">Foo</span> <span class="Operator">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Exception</span> <span class="Comment"># bad style, try to inherit CatchableError or Defect</span></pre></p>
</li>
<li><p>Unless marked with the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pure</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma, members of enums should have an identifying prefix, such as an abbreviation of the enum's name.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">PathComponent</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">pcDir</span>
    <span class="Identifier">pcLinkToDir</span>
    <span class="Identifier">pcFile</span>
    <span class="Identifier">pcLinkToFile</span></pre></p>
</li>
<li><p>Non-pure enum values should use camelCase whereas pure enum values should use PascalCase.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">PathComponent</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">pure</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span> <span class="Keyword">enum</span>
    <span class="Identifier">Dir</span>
    <span class="Identifier">LinkToDir</span>
    <span class="Identifier">File</span>
    <span class="Identifier">LinkToFile</span></pre></p>
</li>
<li>In the age of HTTP, HTML, FTP, TCP, IP, UTF, WWW it is foolish to pretend these are somewhat special words requiring all uppercase. Instead treat them as what they are: Real words. So it's <tt class="docutils literal"><span class="pre"><span class="Identifier">parseUrl</span></span></tt> rather than <tt class="docutils literal"><span class="pre"><span class="Identifier">parseURL</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">checkHttpHeader</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">checkHTTPHeader</span></span></tt> etc.</li>
<li>Operations like <tt class="docutils literal"><span class="pre"><span class="Identifier">mitems</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">mpairs</span></span></tt> (or the now deprecated <tt class="docutils literal"><span class="pre"><span class="Identifier">mget</span></span></tt>) that allow a <em>mutating view</em> into some data structure should start with an <tt class="docutils literal"><span class="pre"><span class="Identifier">m</span></span></tt>.</li>
<li>When both in-place mutation and 'returns transformed copy' are available the latter is a past participle of the former:<ul class="simple"><li>reverse and reversed in algorithm</li>
<li>sort and sorted</li>
<li>rotate and rotated</li>
</ul>
</li>
<li>When the 'returns transformed copy' version already exists like <tt class="docutils literal"><span class="pre"><span class="Identifier">strutils</span><span class="Operator">.</span><span class="Identifier">replace</span></span></tt> an in-place version should get an <tt class="docutils literal"><span class="pre">-In</span></tt> suffix (<tt class="docutils literal"><span class="pre"><span class="Identifier">replaceIn</span></span></tt> for this example).</li>
<li>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">subjectVerb</span></span></tt>, not <tt class="docutils literal"><span class="pre"><span class="Identifier">verbSubject</span></span></tt>, e.g.: <tt class="docutils literal"><span class="pre"><span class="Identifier">fileExists</span></span></tt>, not <tt class="docutils literal"><span class="pre"><span class="Identifier">existsFile</span></span></tt>.</li>
</ul>
<p>The stdlib API is designed to be <strong>easy to use</strong> and consistent. Ease of use is measured by the number of calls to achieve a concrete high level action. The ultimate goal is that the programmer can <em>guess</em> a name.</p>
<p>The library uses a simple naming scheme that makes use of common abbreviations to keep the names short but meaningful.</p>
<table border="1" class="docutils"><tr><th>English word</th><th>To use</th><th>Notes</th></tr>
<tr><td>initialize</td><td>initFoo</td><td>initializes a value type <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span></span></tt></td></tr>
<tr><td>new</td><td>newFoo</td><td>initializes a reference type <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span></span></tt> via <tt class="docutils literal"><span class="pre"><span class="Identifier">new</span></span></tt> or a value type <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span></span></tt> with reference semantics.</td></tr>
<tr><td>this or self</td><td>self</td><td>for method like procs, e.g.: <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span> <span class="Identifier">fun</span><span class="Punctuation">(</span><span class="Identifier">self</span><span class="Punctuation">:</span> <span class="Identifier">Foo</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span></span></tt> rationale: <tt class="docutils literal"><span class="pre"><span class="Identifier">self</span></span></tt> is more unique in English than <tt class="docutils literal"><span class="pre"><span class="Identifier">this</span></span></tt>, and <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> would not be DRY.</td></tr>
<tr><td>find</td><td>find</td><td>should return the position where something was found; for a bool result use <tt class="docutils literal"><span class="pre"><span class="Identifier">contains</span></span></tt></td></tr>
<tr><td>contains</td><td>contains</td><td>often short for <tt class="docutils literal"><span class="pre"><span class="Identifier">find</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">&gt;=</span> <span class="DecNumber">0</span></span></tt></td></tr>
<tr><td>append</td><td>add</td><td>use <tt class="docutils literal"><span class="pre"><span class="Identifier">add</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">append</span></span></tt></td></tr>
<tr><td>compare</td><td>cmp</td><td>should return an int with the <tt class="docutils literal"><span class="pre"><span class="Operator">&lt;</span> <span class="DecNumber">0</span></span></tt> <tt class="docutils literal"><span class="pre"><span class="Operator">==</span> <span class="DecNumber">0</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;</span> <span class="DecNumber">0</span></span></tt> semantics; for a bool result use <tt class="docutils literal"><span class="pre"><span class="Identifier">sameXYZ</span></span></tt></td></tr>
<tr><td>put</td><td>put, <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span></span></tt></td><td>consider overloading <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span></span></tt> for put</td></tr>
<tr><td>get</td><td>get, <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt></td><td>consider overloading <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> for get; consider to not use <tt class="docutils literal"><span class="pre"><span class="Identifier">get</span></span></tt> as a prefix: <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">getLen</span></span></tt></td></tr>
<tr><td>length</td><td>len</td><td>also used for <em>number of elements</em></td></tr>
<tr><td>size</td><td>size, len</td><td>size should refer to a byte size</td></tr>
<tr><td>capacity</td><td>cap</td><td></td></tr>
<tr><td>memory</td><td>mem</td><td>implies a low-level operation</td></tr>
<tr><td>items</td><td>items</td><td>default iterator over a collection</td></tr>
<tr><td>pairs</td><td>pairs</td><td>iterator over (key, value) pairs</td></tr>
<tr><td>delete</td><td>delete, del</td><td>del is supposed to be faster than delete, because it does not keep the order; delete keeps the order</td></tr>
<tr><td>remove</td><td>delete, del</td><td>inconsistent right now</td></tr>
<tr><td>include</td><td>incl</td><td></td></tr>
<tr><td>exclude</td><td>excl</td><td></td></tr>
<tr><td>command</td><td>cmd</td><td></td></tr>
<tr><td>execute</td><td>exec</td><td></td></tr>
<tr><td>environment</td><td>env</td><td></td></tr>
<tr><td>variable</td><td>var</td><td></td></tr>
<tr><td>value</td><td>value, val </td><td>val is preferred, inconsistent right now</td></tr>
<tr><td>executable</td><td>exe</td><td></td></tr>
<tr><td>directory</td><td>dir</td><td></td></tr>
<tr><td>path</td><td>path</td><td>path is the string &quot;/usr/bin&quot; (for example), dir is the content of &quot;/usr/bin&quot;; inconsistent right now</td></tr>
<tr><td>extension</td><td>ext</td><td></td></tr>
<tr><td>separator</td><td>sep</td><td></td></tr>
<tr><td>column</td><td>col, column </td><td>col is preferred, inconsistent right now</td></tr>
<tr><td>application</td><td>app</td><td></td></tr>
<tr><td>configuration</td><td>cfg</td><td></td></tr>
<tr><td>message</td><td>msg</td><td></td></tr>
<tr><td>argument</td><td>arg</td><td></td></tr>
<tr><td>object</td><td>obj</td><td></td></tr>
<tr><td>parameter</td><td>param</td><td></td></tr>
<tr><td>operator</td><td>opr</td><td></td></tr>
<tr><td>procedure</td><td>proc</td><td></td></tr>
<tr><td>function</td><td>func</td><td></td></tr>
<tr><td>coordinate</td><td>coord</td><td></td></tr>
<tr><td>rectangle</td><td>rect</td><td></td></tr>
<tr><td>point</td><td>point</td><td></td></tr>
<tr><td>symbol</td><td>sym</td><td></td></tr>
<tr><td>literal</td><td>lit</td><td></td></tr>
<tr><td>string</td><td>str</td><td></td></tr>
<tr><td>identifier</td><td>ident</td><td></td></tr>
<tr><td>indentation</td><td>indent</td><td></td></tr>
</table>
<h3><a class="toc-backref" id="style-guidelines-coding-conventions" href="#style-guidelines-coding-conventions">Coding Conventions</a></h3><ul class="simple"><li><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">return</span></span></tt> statement should ideally be used when its control-flow properties are required. Use a procedure's implicit <tt class="docutils literal"><span class="pre"><span class="Identifier">result</span></span></tt> variable whenever possible. This improves readability.</p>
<p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">repeat</span><span class="Punctuation">(</span><span class="Identifier">text</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
  <span class="Identifier">result</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span>
  
  <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.</span><span class="Identifier">x</span><span class="Punctuation">:</span>
    <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="Operator">$</span><span class="Identifier">i</span><span class="Punctuation">)</span></pre></p>
</li>
<li>Use a proc when possible, only using the more powerful facilities of macros, templates, iterators, and converters when necessary.</li>
<li>Use the <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statement (not the <tt class="docutils literal"><span class="pre"><span class="Keyword">var</span></span></tt> statement) when declaring variables that do not change within their scope. Using the <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span></span></tt> statement ensures that variables remain immutable, and gives those who read the code a better idea of the code's purpose.</li>
</ul>

<h3><a class="toc-backref" id="style-guidelines-conventions-for-multiminusline-statements-and-expressions" href="#style-guidelines-conventions-for-multiminusline-statements-and-expressions">Conventions for multi-line statements and expressions</a></h3><ul class="simple"><li><p>Tuples which are longer than one line should indent their parameters.</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">LongTupleA</span> <span class="Operator">=</span> <span class="Keyword">tuple</span><span class="Punctuation">[</span>
    <span class="Identifier">wordyTupleMemberOne</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">wordyTupleMemberTwo</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span>
    <span class="Identifier">wordyTupleMemberThree</span><span class="Punctuation">:</span> <span class="Identifier">float</span><span class="Punctuation">]</span></pre></p>
</li>
<li><p>Similarly, any procedure and procedure type declarations that are longer than one line should do the same thing. Double indent may be used to distinguish them from the body that follows - this applies to all constructs with a body (if, while, etc).</p>
<p><pre class="listing"><span class="Keyword">type</span>
  <span class="Identifier">EventCallback</span> <span class="Operator">=</span> <span class="Keyword">proc</span><span class="Punctuation">(</span>
    <span class="Identifier">timeReceived</span><span class="Punctuation">:</span> <span class="Identifier">Time</span><span class="Punctuation">,</span> <span class="Identifier">errorCode</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">event</span><span class="Punctuation">:</span> <span class="Identifier">Event</span><span class="Punctuation">,</span>
    <span class="Identifier">output</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">string</span><span class="Punctuation">)</span>

<span class="Keyword">proc</span> <span class="Identifier">lotsOfArguments</span><span class="Punctuation">(</span>
    <span class="Identifier">argOne</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">argTwo</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">argThree</span><span class="Punctuation">:</span> <span class="Identifier">float</span><span class="Punctuation">,</span>
    <span class="Identifier">argFour</span><span class="Punctuation">:</span> <span class="Keyword">proc</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">argFive</span><span class="Punctuation">:</span> <span class="Identifier">bool</span><span class="Punctuation">,</span> <span class="Identifier">argSix</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
<span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">GenericType</span><span class="Punctuation">[</span><span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">heyLookALongPragma</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
  <span class="Keyword">discard</span></pre></p>
</li>
<li><p>Multi-line procedure calls should continue indented (like multi-line procedure declarations).</p>
<p><pre class="listing"><span class="Identifier">startProcess</span><span class="Punctuation">(</span>
  <span class="Identifier">nimExecutable</span><span class="Punctuation">,</span> <span class="Identifier">currentDirectory</span><span class="Punctuation">,</span> <span class="Identifier">compilerArguments</span>
  <span class="Identifier">environment</span><span class="Punctuation">,</span> <span class="Identifier">processOptions</span><span class="Punctuation">)</span></pre></p>
</li>
</ul>
<p>Previous versions of this guide advocated vertical alignment along the opening brace / parenthesis - both styles are permissible with a preference for the current style in new code.</p>

<h3><a class="toc-backref" id="style-guidelines-miscellaneous" href="#style-guidelines-miscellaneous">Miscellaneous</a></h3><ul class="simple"><li>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">..</span><span class="Identifier">b</span></span></tt> instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">..</span> <span class="Identifier">b</span></span></tt>, except when <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span></span></tt> contains an operator, for example <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">..</span> <span class="Operator">-</span><span class="DecNumber">3</span></span></tt>. Likewise with <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">..&lt;</span><span class="Identifier">b</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span><span class="Operator">..^</span><span class="Identifier">b</span></span></tt> and other operators starting with <tt class="docutils literal"><span class="pre"><span class="Operator">..</span></span></tt>.</li>
<li>Use <tt class="docutils literal"><span class="pre"><span class="Identifier">std</span></span></tt> prefix for standard library modules, namely use <tt class="docutils literal"><span class="pre"><span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">os</span></span></tt> for single module and use <tt class="docutils literal"><span class="pre"><span class="Identifier">std</span><span class="Operator">/</span><span class="Punctuation">[</span><span class="Identifier">os</span><span class="Punctuation">,</span> <span class="Identifier">sysrand</span><span class="Punctuation">,</span> <span class="Identifier">posix</span><span class="Punctuation">]</span></span></tt> for multiple modules.</li>
<li><p>Prefer multiline triple quote literals to start with a newline; it's semantically identical (it's a feature of triple quote literals) but clearer because it aligns with the next line:</p>
<p>use this:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
foo
bar
&quot;&quot;&quot;</span></pre></p>
<p>instead of:</p>
<p><pre class="listing"><span class="Keyword">let</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;foo
bar
&quot;&quot;&quot;</span></pre></p>
</li>
<li>A getter API for a private field <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> should preferably be named <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt>, not <tt class="docutils literal"><span class="pre"><span class="Identifier">getFoo</span></span></tt>. A getter-like API should preferably be named <tt class="docutils literal"><span class="pre"><span class="Identifier">getFoo</span></span></tt>, not <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> if:<ul class="simple"><li>the API has side effects</li>
<li>or the cost is not <tt class="docutils literal"><span class="pre"><span class="Identifier">O</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span></span></tt></li>
</ul>
<p>For in between cases, there is no clear guideline.</p>
</li>
<li>Likewise with a setter API, replacing <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt> with <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span><span class="Operator">=</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">getFoo</span></span></tt> with <tt class="docutils literal"><span class="pre"><span class="Identifier">setFoo</span></span></tt> in the above text.</li>
</ul>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-01-09 11:59:35 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>