elua/doc/en/arch_coding.html

$$HEADER$$
<h3>The eLua coding style</h3>
<p>This section presents the <b>eLua</b> coding style that should be followed by every developer working on <b>eLua</b>. The following rules apply:</p>
<ol>
  <li>Everything should be spaced out properly. Examples (please note the spacing rules, which is basically "space out everything for readability"):
  <pre><code>i = 3 (not i=3)
a = ( a + 5 ) / 3
for( i = 0; i &lt; 10; i ++ ) ...
if( ( i == 5 ) &amp;&amp; ( a == 10 ) ) ...
unsigned i = ( unsigned )p;
void func( int arg1, const char* arg2 ) ...</code></pre></li>
  <li><b>Indentation</b>: indent everything at 2 SPACES. Again, <b>SPACES</b>. <span class="warning">DO NOT USE TABS</span>; this is important (and fortunately pretty easy to remember :) ). 
  There are too many examples where tabs completely destroyed the readability of source code. Most editors have an "insert tabs instead of spaces" option; 
  use it, and set your "tab size" to 2.<br>
  Also, indent "{" and "}" on their own lines:
  <pre><code>if( i == 2 )
{
  // some code here
}
else
{
  // some other code here
}</code></pre>

      Or:
<pre><code>void f( int i )
{
  // function code
}</code></pre>

Do not enclose single statements in {} when given a choice. For example, do this:

<pre><code>if( i == 2 )
  return;</code></pre>
          
          instead of this:
<pre><code>if( i == 2 )
{
  return;
}</code></pre>

Also, follow the "one statement per line" rule. In other words, don't do this:

<pre><code>if( i == 2 ) return;</code></pre>

Do this instead:

<pre><code>if( i == 2 )
  return;</code></pre>

Note that <b>eLua</b> code does not use a space between the function name and its parameter list when calling/defining it (like in the Lua code, for example). So do this:

<pre><code>void f( int i )
{
  // function code here
}

f( 2 ); // function call</code></pre>

instead of this:

<pre><code>void f ( int i )
{
  // function code here
}

f ( 2 ); // function call</code></pre></li>
<li><b>line terminators</b>: <span class="warning">THIS IS IMPORTANT!</span> Use UNIX style (LF) line terminators, not DOS (CR/LF) or old Mac (CR) line terminators.</li>
<li><b>identifier names</b>: use a "GNU-style" here, with underlines and all lowercase:

 <pre><code>int simple;
double another_identifier;
char yes_this_is_OK_although_quite_stupid;</code></pre>

As opposed to:

 <pre><code>int Simple1;
double AnotherIdentifier;
char DontEvenThinkAboutWritingSomethingLikeThis;</code></pre>
<b>DO NOT USE HUNGARIAN NOTATION</b> (like iNumber, sString, fFloat ... if you don't know what that is, it's fine, as it means that we don't need to worry about it :) ). It has its advantages
when used properly, it's just not for <b>eLua</b>.
</li>
<li><b>constants in code</b>: don't ever write something like this:

 <pre><code>if( key == 10 )
  sys_ok();
else if( key == 5 )
  phone_dial( "911" );
else if( key == 666 )
{
  while( user_is_evil() )
    exorcize_user();
}
else if( key == 0 )
 sys_retry();
else
 sys_error();</code></pre>

Instead, define some constants with meaningful names (via enums or even #define) and write like this:

 <pre><code>if( key == KEY_CODE_OK )
  sys_ok();
else if( key == KEY_CODE_FATAL_ERROR )
  phone_dial( "911" );
else if( key == KEY_CODE_COMPLETELY_EVIL )
{
  while( user_is_evil() )
    exorcize_user();
}
else if( key == KEY_CODE_NONE )
  sys_retry();
else
  sys_error();</code></pre>
You can see in this example an accepted violation of the "one statement per line" rule: it's OK to write "else if (newcondition)" on the same line.</li>

<li>use specific data types as much as possible. In this context, <b>specific data types</b> refers to generic types that have the same size on all 
  platforms. They are defined by each platform in turn and their meaning is given below:
  <ul>
    <li><b>s8</b>: signed 8-bit integer</li>
    <li><b>u8</b>: unsigned 8-bit integer</li>
    <li><b>s16</b>: signed 16-bit integer</li>
    <li><b>u16</b>: unsigned 16-bit integer</li>
    <li><b>s32</b>: signed 32-bit integer</li>
    <li><b>u32</b>: unsigned 32-bit integer</li>
    <li><b>s64</b>: signed 64-bit integer</li>
    <li><b>u64</b>: unsigned 64-bit integer</li>
  </ul>
  By writing your code to take advantage of these specific data types you ensure high portability of the code amongst different hardware platforms. Don't
  overuse this rule though. For example, a <b>for</b> loop has generally an <b>int</b> index, which is perfectly fine. But when you specify a timeout that
  must fit in 32 bits, definitely declare it as <b>u32 to</b> instead of <b>unsigned int to</b>.
</li>

<li><b>endianness</b>: remember that <b>eLua</b> runs on both little endian and big endian architectures, and write your code accordingly.</li>

<li><b>comments</b>: we generally favor C++ style comments (//), but it's perfectly OK to use C style (/**/) comments. Automatic documentation generators like Doxygen aren't encouraged, since 
  they tend to make the programmer over-document the code to the point where it becomes hard to read because of the documentation alone. Ideally, you'd neither over-document, nor 
  under-document your code; just document it as much as you think it's needed, without getting into too much details, but also without omitting important information. In particular, DON'T do this:

 <pre><code>// This function returns the sum of two numbers
// Input: n1 - first number
// Input: n2 - the second number
// Output: the sum of n1 and n2
int sum( int n1, int n2 )
{
  return n1 + n2;
}</code></pre>

  When something is self-obvious from the context, documenting it more is pointless and decreases readability.</li>
<li><b>pseudo name-spaces</b>: since we don't have namespaces in C, I like to "emulate" them by prefixing anything (constants, variables, functions) in a file with something that identifies that 
  file uniquely (most likely its name, but this is not a definite rule). For example, a file called "uart.c" would look like this:

 <pre><code>int uart_tx_count, uart_rx_count;

int uart_receive( unsigned limit )...
unsigned uart_send( const char *buf, unsigned size )...</code></pre>
</li>

</ol>
<p>Also, if you're using 3rd party code (from a library/support package for example) making it follow the above rules is nice, but not mandatory. Focus on functionality and writing your own code properly, and come back to indent other people's code when you really don't have anything better to do with your time.</p>
$$FOOTER$$