Wiki Diff CodingConvention, revision #2 to tip
These are coding conventions and requirements for code accepted into Euphoria. These are simple rules right now, but we will expand this document in the future.
The purpose of this document is solely to protect the future of Euphoria. Source code and development without rules only lead to a tangled mess that will soon be abandoned.
# ##global## should never be used.
# Before submitting any new functions, it must contain basic tests proving it at least functions and documentation. The documentation should include a general description, detailed parameter descriptions and detailed return value (if a function). If at all possible, an example is highly recommended. Optional sections include Comments, which are any special notes the user might need to be aware of and also a See Also section.
# Before committing code, tests should be run (all tests, not just new functionality tests)
# Source files should be indented with a tab character, not spaces.
# Reuse the standard library, do not reinvent the wheel.
# Choose good, descriptive names but not too lengthy. Use good judgement finding a happy medium.
# Lines should be limited to no more than 100 characters. Consider breaking a line around the 90 character mark.
## This includes comments. Comments should not be word wrapped by your editor, but at the no more than 100 char mark.
## This includes all text documents.
# Use tabs to indent.
# Set the tab size to 4 characters.
# Avoid trailing whitespace on lines.
# Unsafe string operations have been removed from Euphoria and should not be reintroduced. Use snprintf and strlcpy.
=== Source Formatting
==== Continued Lines
Characters that cause a line continuation should be at the end of the line. For instance, this is good:
<eucode>
sequence email_message = "Hello John Doe! We hope that you are having a good day." &
"bye!"
atom age = to_second(date_of_birth) + to_seconds(now()) *
365 / 8.2 - 12
</eucode>
Continuation characters at the beginning of the line do not read correctly. For instance:
<eucode>
sequence email_message = "Hello John Doe! we hope that you are having a good day "
& "bye!"
atom age = to_second(date_of_birth) + to_seconds(now())
* 365 / 8.2 - 12
</eucode>
Both of the above example as one reads from left to right, their eyes get to the end of the line and their is no indication that the statement actually continues. A simple "bye" may be missed easily.
==== Routine Parameter Indents
When you must wrap the parameters to a function, do so with three indents.
<eucode>
public function database_open(sequence name, sequence username="unknown", sequence password="unknown",
integer port=1000, sequence other_options="unknown")
integer abc = 12
-- more code
end function
</eucode>
If you indent with only one, like a normal line continuation, then things get confusing fast:
<eucode>
public function database_open(sequence name, sequence username="unknown", sequence password="unknown",
integer port=1000, sequence other_options="unknown")
integer abc = 12
-- more code
end function
</eucode>
==== If/For/While Indents
When you must wrap the conditions on these statements, their trailing word should appear at the same level as their beginning word and the next statement should be indented from there:
<eucode>
if equal(username, "johndoe") or equal(username, "jeffdoe") or
(is_admin = 1 and is_disabled = 0)
then
permission_granted = 1
end if
</eucode>
The alternative is pretty hard to read:
<eucode>
if equal(username, "johndoe") or equal(username, "jeffdoe") or
(is_admin = 1 and is_disabled = 0) then
permission_granted = 1
end if
</eucode>
PL (24/05/2011): The correct indent IMO is:
<eucode>
if equal(username, "johndoe")
or equal(username, "jeffdoe")
or (is_admin = 1 and is_disabled = 0) then
permission_granted = 1
end if
</eucode>
==== Multi-line/Multi-element sequences
Sequences should be indented with the beginning { at the end of the line and the ending } at the same indent level as where it was defined:
<eucode>
sequence names = {
"John",
"Jim",
"Jack",
"Jane"
}
</eucode>
Trying to create something similar to [[this|http://www.softwareprojects.com/resources/programming/t-software-projects-coding-convention-1614.html]].
==Variable names==
All strings must be prefixed by a lowercase s, followed by first letter of every word in caps.
Example:
sequence sMyString, sName
All integers must be prefixed by a lowercase i, followed by first letter of every word in caps.
Example:
integer iAge
Exceptions when you don't need to prefix a variable name by i, are the following variable names: maxlen, i, j, k
All atoms must be prefixed by a lowercase a, followed by first letter of every word in caps.
Example:
atom aYear
All booleans and flags (even if you're using an integer to identify 0/1 condition) must be prefixed by a lowercase b, followed by first letter of every word in caps.
Example:
integer bFirstTime, bSeenBefore
All other variable names must be all lower case. Multiple words separated with an underscore.
Example:
age = 25
customer_age = 31
==Function Names==
Function names must have first letter of every word in caps.
Example:
function MyFunction(...)
Exceptions: System functions and runtime functions should remain all lowercase (i.e. strcmp, stripslashes)
==Constants==
Constant names should always be all caps.
Example:
constant MAX_NUM_DAYS_IN_MONTH = 31
==Indentation==
Avoid using spaces for indentation. Start your code at the far left corner and use tabs for indentation.
Example:
{{{
function MyFunction($variable)
-- Do something
puts(1,"Hello World")
if (1 == 1)
-- Do something else
puts(1,"Goodbye")
end if
end function
}}}
When assigning values into multiple related variables, always left justify assignments.
Example:
{{{
-- set post username/password
input[1] = account_id
input[2] = password
input[3] = sessid2
}}}
==Function Return Values==
==Spacing==
Comment, followed by one line of code, followed by one line of space.
Example:
{{{
-- Store 1 into my_variable
my_variable = 1
-- Display the value in my_variable
puts(1,my_variable)
}}}
==Code Process Flow==
Avoid using a return/exit in the middle of your code. Every function should have a single return at the end.
Use do {} while(0) loops with breaks to control execution.
Example:
{{{
int VeryLongFunction()
{
// Initialize
$iResult = 0;
do
{
// Test something
if ($condition)
{
// Oops. We have to bail
break;
}
// Do something
// ...
// Test something else
if ($another_condition)
{
// Oops. We have to bail
break;
}
// If we're up to here - all is well
$iResult = 1;
} while (0);
// Return result
return $iResult;
}
}}}
==Comment Style==
EVERY SINGLE LINE of your code must be prefixed with a {{{-- comment}}}. There is no exception to this rule.
As for what each comment should say - a nonprogrammer reading your comments top to bottom, should be able to fully understand what the function is doing.
Example:
{{{
-- Display Hello World
puts(1,"Hello World")
-- Check to see if 1 equals 2
if 1=2 then
-- 1 does equal 2, the end of the world must be coming
-- Display end of the world
puts(1,"It's the end of the world as we know it")
-- (Else - 1 does not equal 2)
else
-- We're in good shape
-- Display all is well message
puts(1,"All is well")
end if
Every function must be prefixed with a -- comment block outlining input, output and return parameters.
Start with a few lines describing what the function does, follow with a list of all input parameters, then all output (pass by reference) parameters and finally the function return value.
Include another empty line with -- at the end of the function description
Use this block as a template:
{{{
-- Attempt to charge customer and process order
--
-- Input:
-- store_id - Your store ID
-- product_codename - The unique product codename
--
-- Output:
-- order_id - On return will hold order id
-- ResultStr - On return will hold Error string
--
-- Returns:
-- Order ID if successful or 0 if failed
--
function do_checkout(atom store_id, sequence product_codename, atom order_id, sequence ResultStr)
..
end function
}}}
==Other important Good Programming Practices==
1. Initialize all variables BEFORE using them
Example:
{{{
function MyFunction()
integer
iResult = 0;
-- Now do something
-- ...
end function
}}}
2. Do NOT rely on global variables.
3. When returning error strings, always return meaningful error strings that a person other than yourself can understand
4. Try to avoid sprinkling new variables into the global scope. Try to keep all variables confined to the scope of a single function
5. Avoid long functions (two pages or more). Split to smaller internal functions as needed and prefix the internal function with an uppercase I for clarity.
Example:
{{{
function MyLongFunction()
-- Wash clothes
IWashClothers()
-- Now dry them up
IDryCycle()
-- Notify master that laundry is done
INotifyMaster()
end function
}}}
6. Avoid reusing the same variable in a function for two different purposes (unless it's an i, j, k loop counter)
7. As you develop new functions - "Black box test" your functions in a standalone environment, by calling them from a test shell script.
Then after committing your code to the live environment, "White box test" your code by running through a complete cycle start to finish.
The purpose of this document is solely to protect the future of Euphoria. Source code and development without rules only lead to a tangled mess that will soon be abandoned.
# ##global## should never be used.
# Before submitting any new functions, it must contain basic tests proving it at least functions and documentation. The documentation should include a general description, detailed parameter descriptions and detailed return value (if a function). If at all possible, an example is highly recommended. Optional sections include Comments, which are any special notes the user might need to be aware of and also a See Also section.
# Before committing code, tests should be run (all tests, not just new functionality tests)
# Source files should be indented with a tab character, not spaces.
# Reuse the standard library, do not reinvent the wheel.
# Choose good, descriptive names but not too lengthy. Use good judgement finding a happy medium.
# Lines should be limited to no more than 100 characters. Consider breaking a line around the 90 character mark.
## This includes comments. Comments should not be word wrapped by your editor, but at the no more than 100 char mark.
## This includes all text documents.
# Use tabs to indent.
# Set the tab size to 4 characters.
# Avoid trailing whitespace on lines.
# Unsafe string operations have been removed from Euphoria and should not be reintroduced. Use snprintf and strlcpy.
=== Source Formatting
==== Continued Lines
Characters that cause a line continuation should be at the end of the line. For instance, this is good:
<eucode>
sequence email_message = "Hello John Doe! We hope that you are having a good day." &
"bye!"
atom age = to_second(date_of_birth) + to_seconds(now()) *
365 / 8.2 - 12
</eucode>
Continuation characters at the beginning of the line do not read correctly. For instance:
<eucode>
sequence email_message = "Hello John Doe! we hope that you are having a good day "
& "bye!"
atom age = to_second(date_of_birth) + to_seconds(now())
* 365 / 8.2 - 12
</eucode>
Both of the above example as one reads from left to right, their eyes get to the end of the line and their is no indication that the statement actually continues. A simple "bye" may be missed easily.
==== Routine Parameter Indents
When you must wrap the parameters to a function, do so with three indents.
<eucode>
public function database_open(sequence name, sequence username="unknown", sequence password="unknown",
integer port=1000, sequence other_options="unknown")
integer abc = 12
-- more code
end function
</eucode>
If you indent with only one, like a normal line continuation, then things get confusing fast:
<eucode>
public function database_open(sequence name, sequence username="unknown", sequence password="unknown",
integer port=1000, sequence other_options="unknown")
integer abc = 12
-- more code
end function
</eucode>
==== If/For/While Indents
When you must wrap the conditions on these statements, their trailing word should appear at the same level as their beginning word and the next statement should be indented from there:
<eucode>
if equal(username, "johndoe") or equal(username, "jeffdoe") or
(is_admin = 1 and is_disabled = 0)
then
permission_granted = 1
end if
</eucode>
The alternative is pretty hard to read:
<eucode>
if equal(username, "johndoe") or equal(username, "jeffdoe") or
(is_admin = 1 and is_disabled = 0) then
permission_granted = 1
end if
</eucode>
PL (24/05/2011): The correct indent IMO is:
<eucode>
if equal(username, "johndoe")
or equal(username, "jeffdoe")
or (is_admin = 1 and is_disabled = 0) then
permission_granted = 1
end if
</eucode>
==== Multi-line/Multi-element sequences
Sequences should be indented with the beginning { at the end of the line and the ending } at the same indent level as where it was defined:
<eucode>
sequence names = {
"John",
"Jim",
"Jack",
"Jane"
}
</eucode>
