eLua Development

IMPORTANT: eLua coding style

Classic

List

Threaded

8 messages Options

BogdanM

IMPORTANT: eLua coding style

Hello all,

This is something I should've done quite some time ago: a coding style for
all eLua contributors. Find it below, and please try to follow it as much as
possible. Also, this is the first time I'm writing a "coding style", so
please let me know if something is missing from the picture.

*1*. Everything should be spaced out properly. Examples (please note the
spacing rules, which is basically "space out everything for readability"):

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 ) ...

*2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO NOT USE
TABS*; this is important (and fortunately pretty easy to remember :) ). I
saw so many examples where tabs completely fucked up the readability of
source code that I don't want to hear about them again. Most editors have an
"insert tabs instead of spaces" option; use it, and set your "tab size" to
2.

Also, indent "{" and "}" on their own lines:

if( i == 2 )
{
// some code here
}
else
{
// some other code here
}

Or:

void f( int i )
{
// function code
}

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

if( i == 2 )
return;

instead of this:

if( i == 2 )
{
return;
}

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

if( i == 2 ) return;

Do this instead:

if( i == 2 )
return;

Note that I'm not using a space between the function name and its parameter
list when calling/defining it (I saw that this happens in the Lua code, for
example). So do this:

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

f( 2 ); // function call

instead of this:

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

f ( 2 ); // function call

*3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF) line
terminators, not DOS (CR/LF) or old Mac (CR).

*4*. Comments: I generally favour C++ style comments (//), but it's
perfectly OK to use C style (/**/) comments. I don't like automatic
documentation generators like Doxygen, since I think that they tend to make
the programmer overdocument the code to the point where it becomes hard to
read because of the documentation alone. I'm inclined to underdocument my
code; don't follow my style here. 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:

// 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;
}

If you do this, I'll personally hunt you for the rest of your life, or at
least until you give up programming completely :) When something is
self-obvious, documenting it more is pointless and decreases readability.
One more thing: we're not addressing to beginner programmers, but rather to
experienced/senior programmers, which is another good reason not to try to
overdocument your code.

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.

Best,
Bogdan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/6ef0cdd3/attachment.html

Dado Sutter

IMPORTANT: eLua coding style

Thanks Bogdan,
Apart from opening the first { on the same line for blocks, all the rest
is pretty much what I've always used :)
Also, I will only fail the "space out everything" when it is nice to keep
the line under 80 columns.
I'll do my best to keep up with this eLua programming style :)

Best
Dado

On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
bogdan.marinescu at gmail.com> wrote:

> Hello all,
>
> This is something I should've done quite some time ago: a coding style for
> all eLua contributors. Find it below, and please try to follow it as much as
> possible. Also, this is the first time I'm writing a "coding style", so
> please let me know if something is missing from the picture.
>
> *1*. Everything should be spaced out properly. Examples (please note the
> spacing rules, which is basically "space out everything for readability"):
>
> 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 ) ...
>
> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO NOT
> USE TABS*; this is important (and fortunately pretty easy to remember :)
> ). I saw so many examples where tabs completely fucked up the readability of
> source code that I don't want to hear about them again. Most editors have an
> "insert tabs instead of spaces" option; use it, and set your "tab size" to
> 2.
>
> Also, indent "{" and "}" on their own lines:
>
> if( i == 2 )
> {
> // some code here
> }
> else
> {
> // some other code here
> }
>
> Or:
>
> void f( int i )
> {
> // function code
> }
>
> Do not enclose single statements in {} when given a choice. For example, do
> this:
>
> if( i == 2 )
> return;
>
> instead of this:
>
> if( i == 2 )
> {
> return;
> }
>
> Also, follow the "one statement per line" rule. In other words, don't do
> this:
>
> if( i == 2 ) return;
>
> Do this instead:
>
> if( i == 2 )
> return;
>
> Note that I'm not using a space between the function name and its parameter
> list when calling/defining it (I saw that this happens in the Lua code, for
> example). So do this:
>
> void f( int i )
> {
> // function code here
> }
>
> f( 2 ); // function call
>
> instead of this:
>
> void f ( int i )
> {
> // function code here
> }
>
> f ( 2 ); // function call
>
> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF) line
> terminators, not DOS (CR/LF) or old Mac (CR).
>
> *4*. Comments: I generally favour C++ style comments (//), but it's
> perfectly OK to use C style (/**/) comments. I don't like automatic
> documentation generators like Doxygen, since I think that they tend to make
> the programmer overdocument the code to the point where it becomes hard to
> read because of the documentation alone. I'm inclined to underdocument my
> code; don't follow my style here. 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:
>
> // 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;
> }
>
> If you do this, I'll personally hunt you for the rest of your life, or at
> least until you give up programming completely :) When something is
> self-obvious, documenting it more is pointless and decreases readability.
> One more thing: we're not addressing to beginner programmers, but rather to
> experienced/senior programmers, which is another good reason not to try to
> overdocument your code.
>
> 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.
>
> Best,
> Bogdan
>
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/07661586/attachment-0001.html

BogdanM

IMPORTANT: eLua coding style

Yes, thank you, I forgot about that :) Try to keep your code line under 80
columns as much as possible.

Also, other important ideas that I completely forgot about: *

1. Identifier names*. I use a "GNU-style" here, with underlines and all
lowercase:

int simple;
double another_identifier;
char yes_this_is_OK_although_quite_stupid;

As opposed to:

int Simple1;
double AnotherIdentifier;
char DontEvenThinkAboutWritingSomethingLikeThis;

*DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just what I
like to see when reading code.

*2. Constants in the code*: don't ever write something like this:

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();

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

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();

In the code above you can also see an exception to the "one statement on one
line rule": it's OK to write "else if(...)" on the same line (to "emulate"
Lua's "elseif" statement :) ).

*3. Pseudo name-spaces*: 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 (its name, for
example, but you can have exceptions). For example, a file called "uart.c"
would look like this:

int uart_tx_count, uart_rx_count;

int uart_receive( unsigned limit )...
unsigned uart_send( const char *buf, unsigned size )...

Once we get more ideas like this I'll rewrite the whole "document" in one
single piece.

Best,
Bogdan

On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com> wrote:

> Thanks Bogdan,
> Apart from opening the first { on the same line for blocks, all the rest
> is pretty much what I've always used :)
> Also, I will only fail the "space out everything" when it is nice to
> keep the line under 80 columns.
> I'll do my best to keep up with this eLua programming style :)
>
> Best
> Dado
>
>
> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
> bogdan.marinescu at gmail.com> wrote:
>
>> Hello all,
>>
>> This is something I should've done quite some time ago: a coding style for
>> all eLua contributors. Find it below, and please try to follow it as much as
>> possible. Also, this is the first time I'm writing a "coding style", so
>> please let me know if something is missing from the picture.
>>
>> *1*. Everything should be spaced out properly. Examples (please note the
>> spacing rules, which is basically "space out everything for readability"):
>>
>> 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 ) ...
>>
>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO NOT
>> USE TABS*; this is important (and fortunately pretty easy to remember :)
>> ). I saw so many examples where tabs completely fucked up the readability of
>> source code that I don't want to hear about them again. Most editors have an
>> "insert tabs instead of spaces" option; use it, and set your "tab size" to
>> 2.
>>
>> Also, indent "{" and "}" on their own lines:
>>
>> if( i == 2 )
>> {
>> // some code here
>> }
>> else
>> {
>> // some other code here
>> }
>>
>> Or:
>>
>> void f( int i )
>> {
>> // function code
>> }
>>
>> Do not enclose single statements in {} when given a choice. For example,
>> do this:
>>
>> if( i == 2 )
>> return;
>>
>> instead of this:
>>
>> if( i == 2 )
>> {
>> return;
>> }
>>
>> Also, follow the "one statement per line" rule. In other words, don't do
>> this:
>>
>> if( i == 2 ) return;
>>
>> Do this instead:
>>
>> if( i == 2 )
>> return;
>>
>> Note that I'm not using a space between the function name and its
>> parameter list when calling/defining it (I saw that this happens in the Lua
>> code, for example). So do this:
>>
>> void f( int i )
>> {
>> // function code here
>> }
>>
>> f( 2 ); // function call
>>
>> instead of this:
>>
>> void f ( int i )
>> {
>> // function code here
>> }
>>
>> f ( 2 ); // function call
>>
>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF) line
>> terminators, not DOS (CR/LF) or old Mac (CR).
>>
>> *4*. Comments: I generally favour C++ style comments (//), but it's
>> perfectly OK to use C style (/**/) comments. I don't like automatic
>> documentation generators like Doxygen, since I think that they tend to make
>> the programmer overdocument the code to the point where it becomes hard to
>> read because of the documentation alone. I'm inclined to underdocument my
>> code; don't follow my style here. 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:
>>
>> // 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;
>> }
>>
>> If you do this, I'll personally hunt you for the rest of your life, or at
>> least until you give up programming completely :) When something is
>> self-obvious, documenting it more is pointless and decreases readability.
>> One more thing: we're not addressing to beginner programmers, but rather to
>> experienced/senior programmers, which is another good reason not to try to
>> overdocument your code.
>>
>> 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.
>>
>> Best,
>> Bogdan
>>
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/d0e6f942/attachment.html

Dado Sutter

IMPORTANT: eLua coding style

Sync again :)
I also do not tend to use Hungarian Notation too often but sometimes it
can help, if it doesn't ploriferate trhu all the code.
To keep the lines <= 80 columns could be a must here.
To leave a blank line between var declarations and the beginning of the
code would be nice too.

Best
Dado

On Mon, Nov 17, 2008 at 9:14 AM, Bogdan Marinescu <
bogdan.marinescu at gmail.com> wrote:

> Yes, thank you, I forgot about that :) Try to keep your code line under 80
> columns as much as possible.
>
> Also, other important ideas that I completely forgot about: *
>
> 1. Identifier names*. I use a "GNU-style" here, with underlines and all
> lowercase:
>
> int simple;
> double another_identifier;
> char yes_this_is_OK_although_quite_stupid;
>
> As opposed to:
>
> int Simple1;
> double AnotherIdentifier;
> char DontEvenThinkAboutWritingSomethingLikeThis;
>
> *DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just
> what I like to see when reading code.
>
> *2. Constants in the code*: don't ever write something like this:
>
> 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();
>
> Instead, define some constants (via enums or even #define) and write like
> this:
>
> 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();
>
> In the code above you can also see an exception to the "one statement on
> one line rule": it's OK to write "else if(...)" on the same line (to
> "emulate" Lua's "elseif" statement :) ).
>
> *3. Pseudo name-spaces*: 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 (its name, for
> example, but you can have exceptions). For example, a file called "uart.c"
> would look like this:
>
> int uart_tx_count, uart_rx_count;
>
> int uart_receive( unsigned limit )...
> unsigned uart_send( const char *buf, unsigned size )...
>
> Once we get more ideas like this I'll rewrite the whole "document" in one
> single piece.
>
> Best,
> Bogdan
>
>
> On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com>wrote:
>
>> Thanks Bogdan,
>> Apart from opening the first { on the same line for blocks, all the
>> rest is pretty much what I've always used :)
>> Also, I will only fail the "space out everything" when it is nice to
>> keep the line under 80 columns.
>> I'll do my best to keep up with this eLua programming style :)
>>
>> Best
>> Dado
>>
>>
>> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
>> bogdan.marinescu at gmail.com> wrote:
>>
>>> Hello all,
>>>
>>> This is something I should've done quite some time ago: a coding style
>>> for all eLua contributors. Find it below, and please try to follow it as
>>> much as possible. Also, this is the first time I'm writing a "coding style",
>>> so please let me know if something is missing from the picture.
>>>
>>> *1*. Everything should be spaced out properly. Examples (please note the
>>> spacing rules, which is basically "space out everything for readability"):
>>>
>>> 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 ) ...
>>>
>>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO NOT
>>> USE TABS*; this is important (and fortunately pretty easy to remember :)
>>> ). I saw so many examples where tabs completely fucked up the readability of
>>> source code that I don't want to hear about them again. Most editors have an
>>> "insert tabs instead of spaces" option; use it, and set your "tab size" to
>>> 2.
>>>
>>> Also, indent "{" and "}" on their own lines:
>>>
>>> if( i == 2 )
>>> {
>>> // some code here
>>> }
>>> else
>>> {
>>> // some other code here
>>> }
>>>
>>> Or:
>>>
>>> void f( int i )
>>> {
>>> // function code
>>> }
>>>
>>> Do not enclose single statements in {} when given a choice. For example,
>>> do this:
>>>
>>> if( i == 2 )
>>> return;
>>>
>>> instead of this:
>>>
>>> if( i == 2 )
>>> {
>>> return;
>>> }
>>>
>>> Also, follow the "one statement per line" rule. In other words, don't do
>>> this:
>>>
>>> if( i == 2 ) return;
>>>
>>> Do this instead:
>>>
>>> if( i == 2 )
>>> return;
>>>
>>> Note that I'm not using a space between the function name and its
>>> parameter list when calling/defining it (I saw that this happens in the Lua
>>> code, for example). So do this:
>>>
>>> void f( int i )
>>> {
>>> // function code here
>>> }
>>>
>>> f( 2 ); // function call
>>>
>>> instead of this:
>>>
>>> void f ( int i )
>>> {
>>> // function code here
>>> }
>>>
>>> f ( 2 ); // function call
>>>
>>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF) line
>>> terminators, not DOS (CR/LF) or old Mac (CR).
>>>
>>> *4*. Comments: I generally favour C++ style comments (//), but it's
>>> perfectly OK to use C style (/**/) comments. I don't like automatic
>>> documentation generators like Doxygen, since I think that they tend to make
>>> the programmer overdocument the code to the point where it becomes hard to
>>> read because of the documentation alone. I'm inclined to underdocument my
>>> code; don't follow my style here. 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:
>>>
>>> // 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;
>>> }
>>>
>>> If you do this, I'll personally hunt you for the rest of your life, or at
>>> least until you give up programming completely :) When something is
>>> self-obvious, documenting it more is pointless and decreases readability.
>>> One more thing: we're not addressing to beginner programmers, but rather to
>>> experienced/senior programmers, which is another good reason not to try to
>>> overdocument your code.
>>>
>>> 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.
>>>
>>> Best,
>>> Bogdan
>>>
>>>
>>> _______________________________________________
>>> Elua-dev mailing list
>>> Elua-dev at lists.berlios.de
>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>
>>>
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/51e5b3fb/attachment-0001.html

Bittencourt

IMPORTANT: eLua coding style

Agreed!

(except the new lines for "{" & "}" , but if its a defined code style. let's
obey!)

A question about style:
If a function call or an conditional clause pass the limit of 80 columns,
what should we do?

I'm used to do something like this;

foo ( aGargantualVariableNameWithLasersAndHorns,
anotherOneButThisTimeWithClawsToo,
pleaseSomeoneKillTheGuyWhoWroteThisNames );

On Mon, Nov 17, 2008 at 9:36 AM, Dado Sutter <dadosutter at gmail.com> wrote:

> Sync again :)
> I also do not tend to use Hungarian Notation too often but sometimes it
> can help, if it doesn't ploriferate trhu all the code.
> To keep the lines <= 80 columns could be a must here.
> To leave a blank line between var declarations and the beginning of the
> code would be nice too.
>
> Best
> Dado
>
>
>
> On Mon, Nov 17, 2008 at 9:14 AM, Bogdan Marinescu <
> bogdan.marinescu at gmail.com> wrote:
>
>> Yes, thank you, I forgot about that :) Try to keep your code line under 80
>> columns as much as possible.
>>
>> Also, other important ideas that I completely forgot about: *
>>
>> 1. Identifier names*. I use a "GNU-style" here, with underlines and all
>> lowercase:
>>
>> int simple;
>> double another_identifier;
>> char yes_this_is_OK_although_quite_stupid;
>>
>> As opposed to:
>>
>> int Simple1;
>> double AnotherIdentifier;
>> char DontEvenThinkAboutWritingSomethingLikeThis;
>>
>> *DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just
>> what I like to see when reading code.
>>
>> *2. Constants in the code*: don't ever write something like this:
>>
>> 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();
>>
>> Instead, define some constants (via enums or even #define) and write like
>> this:
>>
>> 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();
>>
>> In the code above you can also see an exception to the "one statement on
>> one line rule": it's OK to write "else if(...)" on the same line (to
>> "emulate" Lua's "elseif" statement :) ).
>>
>> *3. Pseudo name-spaces*: 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 (its name, for
>> example, but you can have exceptions). For example, a file called "uart.c"
>> would look like this:
>>
>> int uart_tx_count, uart_rx_count;
>>
>> int uart_receive( unsigned limit )...
>> unsigned uart_send( const char *buf, unsigned size )...
>>
>> Once we get more ideas like this I'll rewrite the whole "document" in one
>> single piece.
>>
>> Best,
>> Bogdan
>>
>>
>> On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com>wrote:
>>
>>> Thanks Bogdan,
>>> Apart from opening the first { on the same line for blocks, all the
>>> rest is pretty much what I've always used :)
>>> Also, I will only fail the "space out everything" when it is nice to
>>> keep the line under 80 columns.
>>> I'll do my best to keep up with this eLua programming style :)
>>>
>>> Best
>>> Dado
>>>
>>>
>>> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
>>> bogdan.marinescu at gmail.com> wrote:
>>>
>>>> Hello all,
>>>>
>>>> This is something I should've done quite some time ago: a coding style
>>>> for all eLua contributors. Find it below, and please try to follow it as
>>>> much as possible. Also, this is the first time I'm writing a "coding style",
>>>> so please let me know if something is missing from the picture.
>>>>
>>>> *1*. Everything should be spaced out properly. Examples (please note
>>>> the spacing rules, which is basically "space out everything for
>>>> readability"):
>>>>
>>>> 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 ) ...
>>>>
>>>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO NOT
>>>> USE TABS*; this is important (and fortunately pretty easy to remember
>>>> :) ). I saw so many examples where tabs completely fucked up the readability
>>>> of source code that I don't want to hear about them again. Most editors have
>>>> an "insert tabs instead of spaces" option; use it, and set your "tab size"
>>>> to 2.
>>>>
>>>> Also, indent "{" and "}" on their own lines:
>>>>
>>>> if( i == 2 )
>>>> {
>>>> // some code here
>>>> }
>>>> else
>>>> {
>>>> // some other code here
>>>> }
>>>>
>>>> Or:
>>>>
>>>> void f( int i )
>>>> {
>>>> // function code
>>>> }
>>>>
>>>> Do not enclose single statements in {} when given a choice. For example,
>>>> do this:
>>>>
>>>> if( i == 2 )
>>>> return;
>>>>
>>>> instead of this:
>>>>
>>>> if( i == 2 )
>>>> {
>>>> return;
>>>> }
>>>>
>>>> Also, follow the "one statement per line" rule. In other words, don't do
>>>> this:
>>>>
>>>> if( i == 2 ) return;
>>>>
>>>> Do this instead:
>>>>
>>>> if( i == 2 )
>>>> return;
>>>>
>>>> Note that I'm not using a space between the function name and its
>>>> parameter list when calling/defining it (I saw that this happens in the Lua
>>>> code, for example). So do this:
>>>>
>>>> void f( int i )
>>>> {
>>>> // function code here
>>>> }
>>>>
>>>> f( 2 ); // function call
>>>>
>>>> instead of this:
>>>>
>>>> void f ( int i )
>>>> {
>>>> // function code here
>>>> }
>>>>
>>>> f ( 2 ); // function call
>>>>
>>>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF)
>>>> line terminators, not DOS (CR/LF) or old Mac (CR).
>>>>
>>>> *4*. Comments: I generally favour C++ style comments (//), but it's
>>>> perfectly OK to use C style (/**/) comments. I don't like automatic
>>>> documentation generators like Doxygen, since I think that they tend to make
>>>> the programmer overdocument the code to the point where it becomes hard to
>>>> read because of the documentation alone. I'm inclined to underdocument my
>>>> code; don't follow my style here. 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:
>>>>
>>>> // 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;
>>>> }
>>>>
>>>> If you do this, I'll personally hunt you for the rest of your life, or
>>>> at least until you give up programming completely :) When something is
>>>> self-obvious, documenting it more is pointless and decreases readability.
>>>> One more thing: we're not addressing to beginner programmers, but rather to
>>>> experienced/senior programmers, which is another good reason not to try to
>>>> overdocument your code.
>>>>
>>>> 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.
>>>>
>>>> Best,
>>>> Bogdan
>>>>
>>>>
>>>> _______________________________________________
>>>> Elua-dev mailing list
>>>> Elua-dev at lists.berlios.de
>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>
>>>>
>>>
>>> _______________________________________________
>>> Elua-dev mailing list
>>> Elua-dev at lists.berlios.de
>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>
>>>
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

--
--Pedro Bittencourt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/f72b026d/attachment.html

Dado Sutter

IMPORTANT: eLua coding style

On Mon, Nov 17, 2008 at 12:01 PM, Pedro Bittencourt <
pedrobittencourt87 at gmail.com> wrote:

> Agreed!
>
> (except the new lines for "{" & "}" , but if its a defined code style.
> let's obey!)

He he, I don't like it neather, at least for the first {
But let's obey the Master ! :)

> A question about style:
> If a function call or an conditional clause pass the limit of 80 columns,
> what should we do?
>
> I'm used to do something like this;
>
> foo ( aGargantualVariableNameWithLasersAndHorns,
> anotherOneButThisTimeWithClawsToo,
> pleaseSomeoneKillTheGuyWhoWroteThisNames );

eLua won't have so javalized huge names but yes, I would arrange them as
you've shown, except for the alignment, that I would keep on the first
column right below aGargantua........

Best
Dado

> On Mon, Nov 17, 2008 at 9:36 AM, Dado Sutter <dadosutter at gmail.com> wrote:
>
>> Sync again :)
>> I also do not tend to use Hungarian Notation too often but sometimes it
>> can help, if it doesn't ploriferate trhu all the code.
>> To keep the lines <= 80 columns could be a must here.
>> To leave a blank line between var declarations and the beginning of the
>> code would be nice too.
>>
>> Best
>> Dado
>>
>>
>>
>> On Mon, Nov 17, 2008 at 9:14 AM, Bogdan Marinescu <
>> bogdan.marinescu at gmail.com> wrote:
>>
>>> Yes, thank you, I forgot about that :) Try to keep your code line under
>>> 80 columns as much as possible.
>>>
>>> Also, other important ideas that I completely forgot about: *
>>>
>>> 1. Identifier names*. I use a "GNU-style" here, with underlines and all
>>> lowercase:
>>>
>>> int simple;
>>> double another_identifier;
>>> char yes_this_is_OK_although_quite_stupid;
>>>
>>> As opposed to:
>>>
>>> int Simple1;
>>> double AnotherIdentifier;
>>> char DontEvenThinkAboutWritingSomethingLikeThis;
>>>
>>> *DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just
>>> what I like to see when reading code.
>>>
>>> *2. Constants in the code*: don't ever write something like this:
>>>
>>> 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();
>>>
>>> Instead, define some constants (via enums or even #define) and write like
>>> this:
>>>
>>> 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();
>>>
>>> In the code above you can also see an exception to the "one statement on
>>> one line rule": it's OK to write "else if(...)" on the same line (to
>>> "emulate" Lua's "elseif" statement :) ).
>>>
>>> *3. Pseudo name-spaces*: 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 (its name, for
>>> example, but you can have exceptions). For example, a file called "uart.c"
>>> would look like this:
>>>
>>> int uart_tx_count, uart_rx_count;
>>>
>>> int uart_receive( unsigned limit )...
>>> unsigned uart_send( const char *buf, unsigned size )...
>>>
>>> Once we get more ideas like this I'll rewrite the whole "document" in one
>>> single piece.
>>>
>>> Best,
>>> Bogdan
>>>
>>>
>>> On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com>wrote:
>>>
>>>> Thanks Bogdan,
>>>> Apart from opening the first { on the same line for blocks, all the
>>>> rest is pretty much what I've always used :)
>>>> Also, I will only fail the "space out everything" when it is nice to
>>>> keep the line under 80 columns.
>>>> I'll do my best to keep up with this eLua programming style :)
>>>>
>>>> Best
>>>> Dado
>>>>
>>>>
>>>> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
>>>> bogdan.marinescu at gmail.com> wrote:
>>>>
>>>>> Hello all,
>>>>>
>>>>> This is something I should've done quite some time ago: a coding style
>>>>> for all eLua contributors. Find it below, and please try to follow it as
>>>>> much as possible. Also, this is the first time I'm writing a "coding style",
>>>>> so please let me know if something is missing from the picture.
>>>>>
>>>>> *1*. Everything should be spaced out properly. Examples (please note
>>>>> the spacing rules, which is basically "space out everything for
>>>>> readability"):
>>>>>
>>>>> 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 ) ...
>>>>>
>>>>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO
>>>>> NOT USE TABS*; this is important (and fortunately pretty easy to
>>>>> remember :) ). I saw so many examples where tabs completely fucked up the
>>>>> readability of source code that I don't want to hear about them again. Most
>>>>> editors have an "insert tabs instead of spaces" option; use it, and set your
>>>>> "tab size" to 2.
>>>>>
>>>>> Also, indent "{" and "}" on their own lines:
>>>>>
>>>>> if( i == 2 )
>>>>> {
>>>>> // some code here
>>>>> }
>>>>> else
>>>>> {
>>>>> // some other code here
>>>>> }
>>>>>
>>>>> Or:
>>>>>
>>>>> void f( int i )
>>>>> {
>>>>> // function code
>>>>> }
>>>>>
>>>>> Do not enclose single statements in {} when given a choice. For
>>>>> example, do this:
>>>>>
>>>>> if( i == 2 )
>>>>> return;
>>>>>
>>>>> instead of this:
>>>>>
>>>>> if( i == 2 )
>>>>> {
>>>>> return;
>>>>> }
>>>>>
>>>>> Also, follow the "one statement per line" rule. In other words, don't
>>>>> do this:
>>>>>
>>>>> if( i == 2 ) return;
>>>>>
>>>>> Do this instead:
>>>>>
>>>>> if( i == 2 )
>>>>> return;
>>>>>
>>>>> Note that I'm not using a space between the function name and its
>>>>> parameter list when calling/defining it (I saw that this happens in the Lua
>>>>> code, for example). So do this:
>>>>>
>>>>> void f( int i )
>>>>> {
>>>>> // function code here
>>>>> }
>>>>>
>>>>> f( 2 ); // function call
>>>>>
>>>>> instead of this:
>>>>>
>>>>> void f ( int i )
>>>>> {
>>>>> // function code here
>>>>> }
>>>>>
>>>>> f ( 2 ); // function call
>>>>>
>>>>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF)
>>>>> line terminators, not DOS (CR/LF) or old Mac (CR).
>>>>>
>>>>> *4*. Comments: I generally favour C++ style comments (//), but it's
>>>>> perfectly OK to use C style (/**/) comments. I don't like automatic
>>>>> documentation generators like Doxygen, since I think that they tend to make
>>>>> the programmer overdocument the code to the point where it becomes hard to
>>>>> read because of the documentation alone. I'm inclined to underdocument my
>>>>> code; don't follow my style here. 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:
>>>>>
>>>>> // 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;
>>>>> }
>>>>>
>>>>> If you do this, I'll personally hunt you for the rest of your life, or
>>>>> at least until you give up programming completely :) When something is
>>>>> self-obvious, documenting it more is pointless and decreases readability.
>>>>> One more thing: we're not addressing to beginner programmers, but rather to
>>>>> experienced/senior programmers, which is another good reason not to try to
>>>>> overdocument your code.
>>>>>
>>>>> 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.
>>>>>
>>>>> Best,
>>>>> Bogdan
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Elua-dev mailing list
>>>>> Elua-dev at lists.berlios.de
>>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> Elua-dev mailing list
>>>> Elua-dev at lists.berlios.de
>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>
>>>>
>>>
>>> _______________________________________________
>>> Elua-dev mailing list
>>> Elua-dev at lists.berlios.de
>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>
>>>
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
>
> --
> --Pedro Bittencourt
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/198a0727/attachment-0001.html

BogdanM

IMPORTANT: eLua coding style

In reply to this post by Bittencourt

Yes, that would be quite fine :)

On Mon, Nov 17, 2008 at 4:01 PM, Pedro Bittencourt <
pedrobittencourt87 at gmail.com> wrote:

> Agreed!
>
> (except the new lines for "{" & "}" , but if its a defined code style.
> let's obey!)
>
> A question about style:
> If a function call or an conditional clause pass the limit of 80 columns,
> what should we do?
>
> I'm used to do something like this;
>
> foo ( aGargantualVariableNameWithLasersAndHorns,
> anotherOneButThisTimeWithClawsToo,
> pleaseSomeoneKillTheGuyWhoWroteThisNames );
>
>
>
>
>
> On Mon, Nov 17, 2008 at 9:36 AM, Dado Sutter <dadosutter at gmail.com> wrote:
>
>> Sync again :)
>> I also do not tend to use Hungarian Notation too often but sometimes it
>> can help, if it doesn't ploriferate trhu all the code.
>> To keep the lines <= 80 columns could be a must here.
>> To leave a blank line between var declarations and the beginning of the
>> code would be nice too.
>>
>> Best
>> Dado
>>
>>
>>
>> On Mon, Nov 17, 2008 at 9:14 AM, Bogdan Marinescu <
>> bogdan.marinescu at gmail.com> wrote:
>>
>>> Yes, thank you, I forgot about that :) Try to keep your code line under
>>> 80 columns as much as possible.
>>>
>>> Also, other important ideas that I completely forgot about: *
>>>
>>> 1. Identifier names*. I use a "GNU-style" here, with underlines and all
>>> lowercase:
>>>
>>> int simple;
>>> double another_identifier;
>>> char yes_this_is_OK_although_quite_stupid;
>>>
>>> As opposed to:
>>>
>>> int Simple1;
>>> double AnotherIdentifier;
>>> char DontEvenThinkAboutWritingSomethingLikeThis;
>>>
>>> *DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just
>>> what I like to see when reading code.
>>>
>>> *2. Constants in the code*: don't ever write something like this:
>>>
>>> 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();
>>>
>>> Instead, define some constants (via enums or even #define) and write like
>>> this:
>>>
>>> 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();
>>>
>>> In the code above you can also see an exception to the "one statement on
>>> one line rule": it's OK to write "else if(...)" on the same line (to
>>> "emulate" Lua's "elseif" statement :) ).
>>>
>>> *3. Pseudo name-spaces*: 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 (its name, for
>>> example, but you can have exceptions). For example, a file called "uart.c"
>>> would look like this:
>>>
>>> int uart_tx_count, uart_rx_count;
>>>
>>> int uart_receive( unsigned limit )...
>>> unsigned uart_send( const char *buf, unsigned size )...
>>>
>>> Once we get more ideas like this I'll rewrite the whole "document" in one
>>> single piece.
>>>
>>> Best,
>>> Bogdan
>>>
>>>
>>> On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com>wrote:
>>>
>>>> Thanks Bogdan,
>>>> Apart from opening the first { on the same line for blocks, all the
>>>> rest is pretty much what I've always used :)
>>>> Also, I will only fail the "space out everything" when it is nice to
>>>> keep the line under 80 columns.
>>>> I'll do my best to keep up with this eLua programming style :)
>>>>
>>>> Best
>>>> Dado
>>>>
>>>>
>>>> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
>>>> bogdan.marinescu at gmail.com> wrote:
>>>>
>>>>> Hello all,
>>>>>
>>>>> This is something I should've done quite some time ago: a coding style
>>>>> for all eLua contributors. Find it below, and please try to follow it as
>>>>> much as possible. Also, this is the first time I'm writing a "coding style",
>>>>> so please let me know if something is missing from the picture.
>>>>>
>>>>> *1*. Everything should be spaced out properly. Examples (please note
>>>>> the spacing rules, which is basically "space out everything for
>>>>> readability"):
>>>>>
>>>>> 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 ) ...
>>>>>
>>>>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO
>>>>> NOT USE TABS*; this is important (and fortunately pretty easy to
>>>>> remember :) ). I saw so many examples where tabs completely fucked up the
>>>>> readability of source code that I don't want to hear about them again. Most
>>>>> editors have an "insert tabs instead of spaces" option; use it, and set your
>>>>> "tab size" to 2.
>>>>>
>>>>> Also, indent "{" and "}" on their own lines:
>>>>>
>>>>> if( i == 2 )
>>>>> {
>>>>> // some code here
>>>>> }
>>>>> else
>>>>> {
>>>>> // some other code here
>>>>> }
>>>>>
>>>>> Or:
>>>>>
>>>>> void f( int i )
>>>>> {
>>>>> // function code
>>>>> }
>>>>>
>>>>> Do not enclose single statements in {} when given a choice. For
>>>>> example, do this:
>>>>>
>>>>> if( i == 2 )
>>>>> return;
>>>>>
>>>>> instead of this:
>>>>>
>>>>> if( i == 2 )
>>>>> {
>>>>> return;
>>>>> }
>>>>>
>>>>> Also, follow the "one statement per line" rule. In other words, don't
>>>>> do this:
>>>>>
>>>>> if( i == 2 ) return;
>>>>>
>>>>> Do this instead:
>>>>>
>>>>> if( i == 2 )
>>>>> return;
>>>>>
>>>>> Note that I'm not using a space between the function name and its
>>>>> parameter list when calling/defining it (I saw that this happens in the Lua
>>>>> code, for example). So do this:
>>>>>
>>>>> void f( int i )
>>>>> {
>>>>> // function code here
>>>>> }
>>>>>
>>>>> f( 2 ); // function call
>>>>>
>>>>> instead of this:
>>>>>
>>>>> void f ( int i )
>>>>> {
>>>>> // function code here
>>>>> }
>>>>>
>>>>> f ( 2 ); // function call
>>>>>
>>>>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF)
>>>>> line terminators, not DOS (CR/LF) or old Mac (CR).
>>>>>
>>>>> *4*. Comments: I generally favour C++ style comments (//), but it's
>>>>> perfectly OK to use C style (/**/) comments. I don't like automatic
>>>>> documentation generators like Doxygen, since I think that they tend to make
>>>>> the programmer overdocument the code to the point where it becomes hard to
>>>>> read because of the documentation alone. I'm inclined to underdocument my
>>>>> code; don't follow my style here. 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:
>>>>>
>>>>> // 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;
>>>>> }
>>>>>
>>>>> If you do this, I'll personally hunt you for the rest of your life, or
>>>>> at least until you give up programming completely :) When something is
>>>>> self-obvious, documenting it more is pointless and decreases readability.
>>>>> One more thing: we're not addressing to beginner programmers, but rather to
>>>>> experienced/senior programmers, which is another good reason not to try to
>>>>> overdocument your code.
>>>>>
>>>>> 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.
>>>>>
>>>>> Best,
>>>>> Bogdan
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Elua-dev mailing list
>>>>> Elua-dev at lists.berlios.de
>>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> Elua-dev mailing list
>>>> Elua-dev at lists.berlios.de
>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>
>>>>
>>>
>>> _______________________________________________
>>> Elua-dev mailing list
>>> Elua-dev at lists.berlios.de
>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>
>>>
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
>
> --
> --Pedro Bittencourt
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/a9fea097/attachment-0001.html

Bittencourt

IMPORTANT: eLua coding style

Yes, gMail ruined my alignment...

On Mon, Nov 17, 2008 at 12:08 PM, Bogdan Marinescu <
bogdan.marinescu at gmail.com> wrote:

> Yes, that would be quite fine :)
>
>
> On Mon, Nov 17, 2008 at 4:01 PM, Pedro Bittencourt <
> pedrobittencourt87 at gmail.com> wrote:
>
>> Agreed!
>>
>> (except the new lines for "{" & "}" , but if its a defined code style.
>> let's obey!)
>>
>> A question about style:
>> If a function call or an conditional clause pass the limit of 80 columns,
>> what should we do?
>>
>> I'm used to do something like this;
>>
>> foo ( aGargantualVariableNameWithLasersAndHorns,
>> anotherOneButThisTimeWithClawsToo,
>> pleaseSomeoneKillTheGuyWhoWroteThisNames );
>>
>>
>>
>>
>>
>> On Mon, Nov 17, 2008 at 9:36 AM, Dado Sutter <dadosutter at gmail.com>wrote:
>>
>>> Sync again :)
>>> I also do not tend to use Hungarian Notation too often but sometimes
>>> it can help, if it doesn't ploriferate trhu all the code.
>>> To keep the lines <= 80 columns could be a must here.
>>> To leave a blank line between var declarations and the beginning of
>>> the code would be nice too.
>>>
>>> Best
>>> Dado
>>>
>>>
>>>
>>> On Mon, Nov 17, 2008 at 9:14 AM, Bogdan Marinescu <
>>> bogdan.marinescu at gmail.com> wrote:
>>>
>>>> Yes, thank you, I forgot about that :) Try to keep your code line under
>>>> 80 columns as much as possible.
>>>>
>>>> Also, other important ideas that I completely forgot about: *
>>>>
>>>> 1. Identifier names*. I use a "GNU-style" here, with underlines and all
>>>> lowercase:
>>>>
>>>> int simple;
>>>> double another_identifier;
>>>> char yes_this_is_OK_although_quite_stupid;
>>>>
>>>> As opposed to:
>>>>
>>>> int Simple1;
>>>> double AnotherIdentifier;
>>>> char DontEvenThinkAboutWritingSomethingLikeThis;
>>>>
>>>> *DO NOT USE HUNGARIAN NOTATION !!* (you know, things 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 :) ). I know it's useful, it's not just
>>>> what I like to see when reading code.
>>>>
>>>> *2. Constants in the code*: don't ever write something like this:
>>>>
>>>> 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();
>>>>
>>>> Instead, define some constants (via enums or even #define) and write
>>>> like this:
>>>>
>>>> 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();
>>>>
>>>> In the code above you can also see an exception to the "one statement on
>>>> one line rule": it's OK to write "else if(...)" on the same line (to
>>>> "emulate" Lua's "elseif" statement :) ).
>>>>
>>>> *3. Pseudo name-spaces*: 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 (its name, for
>>>> example, but you can have exceptions). For example, a file called "uart.c"
>>>> would look like this:
>>>>
>>>> int uart_tx_count, uart_rx_count;
>>>>
>>>> int uart_receive( unsigned limit )...
>>>> unsigned uart_send( const char *buf, unsigned size )...
>>>>
>>>> Once we get more ideas like this I'll rewrite the whole "document" in
>>>> one single piece.
>>>>
>>>> Best,
>>>> Bogdan
>>>>
>>>>
>>>> On Mon, Nov 17, 2008 at 12:54 PM, Dado Sutter <dadosutter at gmail.com>wrote:
>>>>
>>>>> Thanks Bogdan,
>>>>> Apart from opening the first { on the same line for blocks, all the
>>>>> rest is pretty much what I've always used :)
>>>>> Also, I will only fail the "space out everything" when it is nice to
>>>>> keep the line under 80 columns.
>>>>> I'll do my best to keep up with this eLua programming style :)
>>>>>
>>>>> Best
>>>>> Dado
>>>>>
>>>>>
>>>>> On Mon, Nov 17, 2008 at 8:43 AM, Bogdan Marinescu <
>>>>> bogdan.marinescu at gmail.com> wrote:
>>>>>
>>>>>> Hello all,
>>>>>>
>>>>>> This is something I should've done quite some time ago: a coding style
>>>>>> for all eLua contributors. Find it below, and please try to follow it as
>>>>>> much as possible. Also, this is the first time I'm writing a "coding style",
>>>>>> so please let me know if something is missing from the picture.
>>>>>>
>>>>>> *1*. Everything should be spaced out properly. Examples (please note
>>>>>> the spacing rules, which is basically "space out everything for
>>>>>> readability"):
>>>>>>
>>>>>> 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 ) ...
>>>>>>
>>>>>> *2*. Indentation: indent everything at 2 SPACES. Again, SPACES. *DO
>>>>>> NOT USE TABS*; this is important (and fortunately pretty easy to
>>>>>> remember :) ). I saw so many examples where tabs completely fucked up the
>>>>>> readability of source code that I don't want to hear about them again. Most
>>>>>> editors have an "insert tabs instead of spaces" option; use it, and set your
>>>>>> "tab size" to 2.
>>>>>>
>>>>>> Also, indent "{" and "}" on their own lines:
>>>>>>
>>>>>> if( i == 2 )
>>>>>> {
>>>>>> // some code here
>>>>>> }
>>>>>> else
>>>>>> {
>>>>>> // some other code here
>>>>>> }
>>>>>>
>>>>>> Or:
>>>>>>
>>>>>> void f( int i )
>>>>>> {
>>>>>> // function code
>>>>>> }
>>>>>>
>>>>>> Do not enclose single statements in {} when given a choice. For
>>>>>> example, do this:
>>>>>>
>>>>>> if( i == 2 )
>>>>>> return;
>>>>>>
>>>>>> instead of this:
>>>>>>
>>>>>> if( i == 2 )
>>>>>> {
>>>>>> return;
>>>>>> }
>>>>>>
>>>>>> Also, follow the "one statement per line" rule. In other words, don't
>>>>>> do this:
>>>>>>
>>>>>> if( i == 2 ) return;
>>>>>>
>>>>>> Do this instead:
>>>>>>
>>>>>> if( i == 2 )
>>>>>> return;
>>>>>>
>>>>>> Note that I'm not using a space between the function name and its
>>>>>> parameter list when calling/defining it (I saw that this happens in the Lua
>>>>>> code, for example). So do this:
>>>>>>
>>>>>> void f( int i )
>>>>>> {
>>>>>> // function code here
>>>>>> }
>>>>>>
>>>>>> f( 2 ); // function call
>>>>>>
>>>>>> instead of this:
>>>>>>
>>>>>> void f ( int i )
>>>>>> {
>>>>>> // function code here
>>>>>> }
>>>>>>
>>>>>> f ( 2 ); // function call
>>>>>>
>>>>>> *3*. Line terminators: *THIS IS IMPORTANT TOO!* Use UNIX style (LF)
>>>>>> line terminators, not DOS (CR/LF) or old Mac (CR).
>>>>>>
>>>>>> *4*. Comments: I generally favour C++ style comments (//), but it's
>>>>>> perfectly OK to use C style (/**/) comments. I don't like automatic
>>>>>> documentation generators like Doxygen, since I think that they tend to make
>>>>>> the programmer overdocument the code to the point where it becomes hard to
>>>>>> read because of the documentation alone. I'm inclined to underdocument my
>>>>>> code; don't follow my style here. 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:
>>>>>>
>>>>>> // 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;
>>>>>> }
>>>>>>
>>>>>> If you do this, I'll personally hunt you for the rest of your life, or
>>>>>> at least until you give up programming completely :) When something is
>>>>>> self-obvious, documenting it more is pointless and decreases readability.
>>>>>> One more thing: we're not addressing to beginner programmers, but rather to
>>>>>> experienced/senior programmers, which is another good reason not to try to
>>>>>> overdocument your code.
>>>>>>
>>>>>> 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.
>>>>>>
>>>>>> Best,
>>>>>> Bogdan
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> Elua-dev mailing list
>>>>>> Elua-dev at lists.berlios.de
>>>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>>>
>>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> Elua-dev mailing list
>>>>> Elua-dev at lists.berlios.de
>>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>>
>>>>>
>>>>
>>>> _______________________________________________
>>>> Elua-dev mailing list
>>>> Elua-dev at lists.berlios.de
>>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>>
>>>>
>>>
>>> _______________________________________________
>>> Elua-dev mailing list
>>> Elua-dev at lists.berlios.de
>>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>>
>>>
>>
>>
>> --
>> --Pedro Bittencourt
>>
>> _______________________________________________
>> Elua-dev mailing list
>> Elua-dev at lists.berlios.de
>> https://lists.berlios.de/mailman/listinfo/elua-dev
>>
>>
>
> _______________________________________________
> Elua-dev mailing list
> Elua-dev at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/elua-dev
>
>

--
--Pedro Bittencourt
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.berlios.de/pipermail/elua-dev/attachments/20081117/b90d8dda/attachment-0001.html