elua/doc/pt/arch_coding.html

$$HEADER$$
<h3>Estilo de codificação em eLua</h3>
<p>Esta seção tem o objetivo de apresentar o estilo de codificação em <b>eLua</b> que deve ser seguido por todo desenvolvedor. Segue abaixo as regras de codificação <b>eLua</b>:
<ol>
  <li>Deve-se formatar o texto adequadamente. Exemplos ("por favor, preste atenção nas regras de espaçamento, pois resumem-se em acrescentar espaços em tudo, com o objetivo de tornar mais f&aacute;cil a leitura do código"):
  <p><pre><code>i = 3 (not i=3)
a = ( a + 5 ) / 3
for( i = 0; i < 10; i++ ) ...
if( ( i == 5 ) && ( a == 10 ) ) ...
unsigned i = ( unsigned )p;
void func( int arg1, const char* arg2 ) ...</code></pre></p></li>
  <li><b>Indentação</b>: Use dois espaços para toda identação. Novamente, <b>ESPAÇOS</b>. <b>N&Atilde;O USE TABS</b>; isto é importante (e felizmente f&aacute;cil de lembrar :) ). 
  Existem muitos exemplos onde tabs estragam completamente a clareza do código fonte. A maioria dos editores de texto t&ecirc;m a opção de "inserção de tabs ao invés de espaços";
  utilize-a e configure o tamanho do TAB para 2.<br>
  Além disso, idente "{" e "}" sobre suas prórias linhas:
  <p><pre><code>if( i == 2 )
{
  // algum código aqui
}
else
{
  // mais algum código aqui
}</code></pre></p>

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

Sempre que possível, não cerque um comando com {}. Por exemplo, faça isso:

<p><pre><code>if( i == 2 )
  return;</code></pre></p>
          
          ao invés disso:
<p><pre><code>if( i == 2 )
{
  return;
}</code></pre></p>

Além disso, siga a regra de "um comando por linha". Em outras palavras, não faça isso:

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

ao invé disso, faça:

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

Observe que o código <b>eLua</b> não usa espaço entre o nome da função e sua lista de parâmetros quando de sua chamada/definição (como no código Lua, por exemplo). So do this:

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

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

instead of this:

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

f ( 2 ); // function call</code></pre></p></li>
<li><b>line terminators</b>: <b>THIS IS IMPORTANT TOO!</b> 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:

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

As opposed to:

 <p><pre><code>int Simple1;
double AnotherIdentifier;
char DontEvenThinkAboutWritingSomethingLikeThis;</code></pre></p>
<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:

 <p><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></p>

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

 <p><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></p>
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 favour 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 overdocument the code to the point where it becomes hard to read because of the documentation alone. Ideally, you'd neither overdocument, nor 
  underdocument 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:

 <p><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></p>

  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:

 <p><pre><code>int uart_tx_count, uart_rx_count;

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

</ol></p>
<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$$