Coding Guidelines

From Pigmeo Development Wiki

Unless specified, all these guidelines are applied to the source code of pigmeo binaries and libraries, NOT code generated by Pigmeo Compiler.

Indentation

Use horizontal tabs ("\t") instead of multiple spaces.

for (int i=0; i < 50; i++) {
   if(i==30) Do.Something();
}

Switch statements have the case more indented than the switch:

switch (x) {
    case 'a':
        int b=5;
        b++;
        break;
    case 'b':
        int c=7;
        c--;
        break;
}

Performance and Readability

When writing pigmeo itself it's more important to be correct and maintainable than to be fast. Fast code that is difficult to maintain is likely going to be looked down upon.

When writing assembly language for the target architectures try to be efficient and add comments explaining how it works.

Where to put spaces

Non't use a space before an opening parenthesis when calling functions, or indexing, like this:

method(a);     array[10]; //good
method (a);     array [10]; //bad

Where to put braces

When defining methods, properties, indexers or other kind of blocks, put the opening brace on the same line as the statement:

public void foo(int a) {
    if(a >= 0) {
        this.b=a;
        this.c=a*500;
    }
}
 
public int bar {
    get {
        return this.fb+7;
    }
}

Use whitespace for clarity

if (a + 5 > method(foo() + 4)); //good
if (a+5 > method(foo()+4)); //acceptable
if (a+5>method(foo()+4)); //bad, please put whitespaces within comparisons

Casing

Arguments, methods, properties, instance fields and everything should use the camel casing for identifiers, like this:

void Method(string myArgument) //good
void Method(string MyArgument) //good
void Method(string strArgument) //bad, avoid type info within names
private int priv_var=6; //bad, avoid visibility info within names
void Method(string lpstrargument) //bad
void Method(string my_argument) //bad

You can do the following:

private List<string> _SomeThing;
public List<string> SomeThing {
    get {
        return _SomeThing;
    }
}

No two identifiers should be differentiated only by case. This causes code portability problems to other programming languages, and reduces readability by developers whose mother's tongue is not english.

Private versus Protected

Protected should be used unless a clear case can be demonstrated why an item should be private.

Constructor Injection

When possible constructor injection should be used. That is, if certain parameters are required for an object to function, force the arguments to be passed in the constructor(s). This forces the developer to pass the arguments during construction rather than after, and greatly simplifies the objects logic and reduces exception paths. This rule could be ignored in certain scenarios where the class is only used by Pigmeo developers, but NEVER within libraries of the Pigmeo Framework used directly by end-users.

Line length

XML documentation must be written in a single line:

/// <summary>
/// This is the summary. You can keep the tags in different lines but this text must be written entirely in a single line. Don't worry if it is very long. Word wrapping must be done in software if you want it.
/// </summary>
/// <remarks>You can put the tags in the same line too</remarks>
void function(){
    ...
}

When declaring or calling a function you should write all of them in a single line unless breaking it in multiple lines enhances readability. It's up to you.

File formats

Save all the files using Windows-style endings and UTF-8 as the charset.

Each source file (there are some exceptions allowed) should only contain one class. Inner classes are allowed. The filename is the same name as the class. So Foo.cs would contain a class named Foo.

Warnings

Avoid commiting code with warnings to the repository, the use of #pragmas to disable warnings is strongly discouraged. Please talk to the rest of developers when you need to ignore a warning and justify the use of the warning ignore clause on a comment.

Note: This refers to warnings thrown by the C# compiler, not those thrown by pigmeo-compiler itself (at the ErrorsAndWarnings class)

Reusability

Ideally we would not need conditional compilation, and the use of #ifdef is strongly discouraged.

All the code must be OS-independent and all the compiled binaries should be executable on any .NET virtual machine (CLR). Avoid p/invokes and unsafe code.

When developing pigmeo-compiler, anything useful for all the architectures must be placed in the frontend and avoid using it only for one arch.

Unimplemented parts

Use ErrorsAndWarnings.Throw().

Programming language

All the code by default must be written in C# >=2.0. If you need C++/CLI ask in the development mailing list.

Some methods of the pigmeo-framework can be implemented in assembly language but they also require a C# implementation that can be debugged and compiled for the architectures which lacks an assembly language implementation.

Avoid using var (anonymous types, available in C# 3.0) when declaring variables. It would be confusing.

Comments and documentation

All the namespaces, classes, methods, static variables, properties, and instance fields commited to the repositories must be documented using XML comments. Local variables can be ignored. All the arguments should be documented, and arguments of public methods in pigmeo-framework MUST be documented (they are going to be used by end-users).

Classes and methods in Pigmeo Framework

Everything being used by end-users should be documented in the website (not only in XML), but even if you don't document it you need to publish at least one example (on the website) about using the class or enum you've just added to Pigmeo Framework. The more methods and properties you show in you examples, the better.

As said before, they must be completely documented using XML comments.