CodingConvention
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:
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
Continuation characters at the beginning of the line do not read correctly. For instance:
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
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.
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
If you indent with only one, like a normal line continuation, then things get confusing fast:
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
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:
if equal(username, "johndoe") or equal(username, "jeffdoe") or (is_admin = 1 and is_disabled = 0) then permission_granted = 1 end if
The alternative is pretty hard to read:
if equal(username, "johndoe") or equal(username, "jeffdoe") or (is_admin = 1 and is_disabled = 0) then permission_granted = 1 end if
PL (24/05/2011): The correct indent IMO is:
if equal(username, "johndoe") or equal(username, "jeffdoe") or (is_admin = 1 and is_disabled = 0) then permission_granted = 1 end if
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:
sequence names = { "John", "Jim", "Jack", "Jane" }