Coding Practices

Coding Practices

Below is a list of coding practices for this project in no necessary order:

Brackets

The proper way to use brackets { } is to put them on the next new line not next to the statement.

INCORRECT

for (int i = 0; i < 5; i++) {
    // code }

CORRECT

for (int i = 0; i < 5; i++)
{
    // code
}

Naming

Function naming should use Pascal case. Camel case and snake case are not accepted.

CORRECT

public static void GetDir (object param1)
{
    // CODE
}

INCORRECT

public static void getDir (object param1)
{
    // CODE
}

INCORRECT

public static void get_dir (object param1)
{
    // CODE
}

Comments

Comment code as often as necessary to clarify what functions or code blocks do. More specifically, place a summary comment before the name of the class to explain its purpose and include any developer notes and TODOs. Try to avoid placing large notes and TODOs in the code itself unless it is required for clarity.

EXAMPLES

/// <summary>
/// Create or update a table in the database
/// </summary>
/// <param name="tablename>Name of the table to be updated</param>
public static bool CreateUpdateTable(string tablename)
{
    // First, we check if the table exists
    ...

    // If it does, update the table
    ...

    // If it doesn't, create the table
    ...

	// TODO: Extract this later
	...
}

Organization

• Avoid duplicating code. If a block of code of significant size (3+ lines usually) is used multiple times within the code, create a method and abstract it. If the block is duplicated across multiple classes, create a helper class (if the function is significantly different than existing classes) to add the method to or add to an existing helper class.
• A class should represent a single function or set of highly related functions. For example, a class should not contain importing and exporting DATs. On the contrary, having similar functions spread across multiple classes is unnecessary. If it's an edge case, contact the project lead for the official ruling.
• Namespacing should be reasonable. Each of the namespaces of the library code represent (mostly)-distinct subsets of functionality. For example, the SabreTools.IO namespace contains both extensions for System.IO objects as well as custom reading and writing.

Code Additions

• Be sure to look around the codebase before deciding to add a new function. Oftentimes, the code already contains something that you can use instead of creating your own version. In the case that it doesn't do exactly what you need, look to see if that function can be changed without affecting current usage. If all else fails, THEN you can create the new function.