Writing readable code is a huge part of easily debugging potential problems. While technically the compiler can read your
code no matter how it's formatted (so long as it is syntactically correct), the compiler isn't the only thing that needs
to read it, humans do too. So making your code "pretty" is a big step in making maintainable, debuggable, and shareable
code. Many code styles are equally readable, and so in many cases, it is pure preference how you choose to format your
code, however, this style guide is what will be used by any standard compliant code formatting tools that may be written
in the future, and so following these examples is good practice.

== Whitespace ==

Technically, most all whitespace is optional. For technical reasons, it is possible to fit all scripts on one line, and no
tabs, spaces, or newlines are required by the lexer. However, this does not lend itself to human readability, so proper
whitespace is vital to making code easily readable.

=== Tabs ===

Many text editors change tabs to spaces, and this is generally undesirable. The general rational behind this is that a tab
is generally more flexible in text editors, it is usually possible to define "tab width," which allows programmers to
customize this to their tastes, without actually having to change the code.

=== Indentation ===

"Code branches", that is conditional blocks, should be indented one tab further than their parent, except in the case of
tertiary usage of an if(). For example:

%%CODE|
if(@condition){
    trueCode();
} else {
    falseCode();
}

proc(_my_proc){
	if(someCondition()){
		return(1);
	} else {
		if(otherCondition()){
			return(2);
		} else if(otherCondition2()){
			return(3);
		} else {
			return(4);
		}
	}
}
%%

The exception is when if is being used as a tertiary statement (that is, the return value of if is not being ignored):

%%CODE|
msg('You wrote ' . if($arg > 0, 'a positive number!', 'a negative number! (or zero!)'));
%%

In general, code should only be nested up to a maximum of 5-7 levels, if you begin to nest deeper than this, consider breaking
code off into a procedure, and calling that procedure. Indentation is one of the most important metrics for making code readable,
and in general, poorly indented code will be far less readable, all other formatting issues aside.

== Ending blocks ==

In cases where you are using multiple blocks, at some point, all the blocks must end. In this case, do not put all the
ending parenthesis on the same line, but instead, match the end parenthesis with the start of the block

%%CODE|
// BAD:
@a = array(
	array(1, 2, 3),
	array(4, 5, 6));

if(@condition){
	code(); }

msg(@a[
	someValue()]);

// Good:
@a = array(
	array(1, 2, 3),
	array(4, 5, 6)
);

if(@condition){
	code();
}

msg(@a[
	someValue()
]);
%%

Using this syntax, should extra code need to be added to the end of the block, it is much easier to locate the
corresponding ending parenthesis/brace/bracket.

== else, and else if ==

In the case of using if or ifelse, it is preferred that brace syntax is used, however, code that still uses the pure
functional approach should follow these guidelines:

The code inside the blocks should be indented one more than the condition statements, but comma that represents the else
should be on a line of its own, and aligned with the parent if. Additionally, a # else comment is helpful.

%%CODE|
if(@condition,
    trueCode()
, // else
    falseCode()
)
%%

Ifelses should follow the same general guidelines, though

%%CODE|
ifelse(@condition1,
    condition1Code()
, @condition2,
    condition2Code()
, // else
    falseCode()
)
%%

{{TakeNote|text=Brace syntax is much preferred in both of these cases}}

== Switch ==

{{function|switch}} statements should use the following format:

%%CODE|
switch(@value){
	case 1:
		codeForCase1();
	case 2:
	case 3:
		codeForCase2();
	default:
		codeForDefault();
}
%%

Note that there is one level of indention for each case, and two levels of indentation for the code
inside the case. The functional usage of switch should never be used, as it is exceedingly difficult
to read.

== Naming Convention ==

Variables should be named using camel case.

%%CODE|
@thisIsAVariable = null; // Good
@this_is_a_variable = null; // Bad
%%

Global procedures should be named using snake case, however.

%%CODE|
/**
 * Good.
 */
proc _this_is_a_proc(){
	return(0);
}

/**
 * Bad.
 */
proc _thisIsAProc(){
	return(1);
}
%%

This aligns with the function naming convention of MethodScript itself: use snake case for globals methods, and camel case
for instance methods.


== Brace Syntax ==

For a full discussion on brace syntax, please see this article: [[Brace_Syntax|Brace Syntax]]. Brace
syntax is preferred in all cases over functional syntax where possible, unless otherwise noted. (Most notably tertiary if
statements.)

== Comments ==
Generally, the double slash (//) is preferred to the number sign (#) for line comments, with the notable exception of
the hashbang at the top of the file, if present. A space should be added after the line comment operator, and before the
first line of the comment text (//Bad) (// Good), the exception being IDE hint comments (i.e. #region)

Block comments that are informational (rather than commenting out code) should follow these conventions: use /* for non
documentation purposes, or for general comment blocks where the comment does not directly correspond with the next
element, for instance, if the comment applies to the whole block of code, or more generally within blocks of code,
rather than in element definitions. Comments that correspond with definitions of elements (classes, variables, procs,
etc) should start with /**, which indicates and enables documentation help for that element in IDEs and reflection.
These types of comments are known as "smart comments" and are treated specially by the compiler, and are not removed at
compile time (though the compiler does otherwise ignore them). In any case, when using either /* or /**, comment blocks
should line up the first star in a column. For blocks of code where the comment is not flush with the left side of the
document, tabs should be used to push the comment block out, and except in the case of the first line, should add a
single space before and after the star. A newline should be added after the begin comment operator, and before the end
comment. The smart comment parser will ignore the first star in a line, and all the beginning whitespace.

<%CODE|
/** Bad comment */
proc _badProcComment(){}

/**
* Bad comment 2, the stars don't line up.
*/
proc _badProcComment2(){}

/**
 * Good comment.
 */
proc _goodProcComment(){}
%>

Divider line comments are generally undesirable (i.e. //----------------------------------------), instead use region
comments, which are hints to IDEs that support the feature, to provide a visual section for you.

<%CODE|
// In IDEs that support this notation, this will create a section for you, and in the editor, should surround the region
// with divider lines.
#region procDefinitions
proc _a(){}
proc _b(){}
#endregion

#region code
_a();
_b();
#endregion 
%>

The descriptions in a smart comment should end with a punctuation mark, and should be complete sentences.

<%CODE|
/**
 * This is a complete sentence, and is good practice for smart comments.
 * @param a This describes what valid and invalid inputs are for this parameter.
 * @return This describes what the return value of the procedure is.
 * @throws IOException This describes in what cases the IOException will be thrown in.
 * @throws IllegalArgumentException This describes in what cases the IllegalArgumentException is thrown in.
 */
int proc _p(string @a) throws IOException, IllegalArgumentException {
	// ...
}
%>