Developers' Guide

Coding guide and workflow

Workflow

We use the fork and pull model of contributions. Please submit pull requests to the CFAN repo, rather than committing directly. This means at least one other person gets to review your code for obvious mistakes before it goes through.

Style

Follow the Framework Design Guidelines. In general this means:

• PascalCase type names
• PascalCase method names
• PascalCase public fields
• _underscoreCamelCase or camelCase private fields
• camelCase local variables

Coding Goals

We'd like the following in our codebase:

• Encourage new contributors.
• Reduce the effort required for code review.
• Reduce technical debt.
• Have a really solid test suite, to provide assurances of code health.
• Have really solid technical documentation, to help new and existing developers alike.

Some ways that we help to achieve this are:

Code each feature or bugfix on a new branch

Using a separate branch for each issue has numerous advantages. When it comes to making a pull-request, there's less code to review, and corrections are easier to track. When testing, it's easier to isolate bugs as there are fewer commits which introduce them.

You can start a new branch off an existing branch that hasn't been merged, if the new work requires the existing changes. However branching of master is preferred when possible, as it means issues in one branch won't hold up other branches waiting to be merged.

It is suggested that branches start with the issue number they address, such as 8_fix_spelling. If a substantive amount of work is to occur, then consider opening an issue for it first. This lets other developers know what's coming, and also prevents them from possibly embarking on something that duplicates or conflicts with your work.

Close issues with commits

Github has the ability to close issues with commits, by including a message such as closes #23 in a commit message. This won't close the commit until it is merged to master.

This means that issues don't remain open when they've been fixed, and conversely ensures that issues don't get closed before they've been

Write tests

Even if they're just placeholders. Each class should have a test file associated with it, and each method should have tests written for it when possible. If a method can't be tested, then consider decomposing it into smaller methods which can.

There are lots of examples in the Tests project, and the NUnit Quickstart is a good place to get started.

Document your code

• While it's ugly, the C# <summary>...</summary> syntax works across IDEs, and provides useful feedback to developers as to what a method does. Consider using it whenever possible.

• Use TODO, FIXME, XXX and NOTE in comments generously. They can highlight where code needs improvement or attention.

• A lot of work on code happens by people who are low on sleep and not familiar with the entire code-base. Add comments generously to help them know what's going on.

Throw exceptions generously

If your code encounters a situation that is likely to be an error, you should throw an exception. Exceptions make it much easier to find and correct problems that were not considered by the calling code. (Contrast with returning an error value, which is easily ignored, and results in hard to find errors later on.)

Our application generated exceptions are called Krakens and all inherit from the Kraken class (which inherits from Exception). See Kraken.cs for what's available.

Catch exceptions sparingly

Catching exceptions that you expect is a very good idea, but don't catch all exceptions, otherwise you may suppress a serious error. catch (FileNotFoundKraken) { } is good but merely catch { } should be used sparingly, if at all.

If you need help, ask!

Don't hesitate to ask for assistance if you need it. Our factorio forums topic is a good place to start, but you can also ask in whichever issue is relevant.

Don't worry about screwing up

These are guidelines only. They're intended to help produce better software, and provider a nicer experience for everyone on the CFAN project, but you're not expected to follow them rigorously. Don't worry if you forget one, or need to bend the rules a little to get things done. We'd rather have your contributions than not have you at all!