Code Conventions

dorkster edited this page Dec 14, 2014 · 3 revisions

Contributing Code

The #1 rule of this project: all non-trivial code changes must be discussed first!

Years of careful decision-making have gone into all parts of this project. Some designs are awaiting planned future changes. If you submit a large patch without knowing how it will affect past and future code, it will be rejected.

Is my code non-trivial? If it touches multiple functions or files, probably so.

Ways to discuss a desired code change:

Pull Requests

When possible, use small pull requests that keep the engine in a stable state. It is far better to have many small pull requests than to wait until your change is too large to merge.

If you're working on more than one feature, submit pull requests separately for these. Some times we need to accept one change and reject the other; if your pull request is all combined I have to reject the entire thing.

Cross-platform considerations

To the best of our ability, we want the code to work on Windows, OSX, Linux and more. We try to isolate platform-specific code and use C preprocessor directives when necessary.

OOP as a last resort

My code is simple (some would say not elegant). I start by coding it the simplest possible way that would work. I have a deep disdain for overengineering.

Action RPGs are a really simple genre. We don't need fully OOP Entity system to create these games.

We have introduced OOP as needed, when the solution makes much more sense than the added complexity. We won't needlessly refactor working code.

No C++11 / C++0x

Maybe we'll allow this kind of code in the future. But Flare has a presence on obscure platforms; I can't guarantee that the compilers have kept up.

Indentation

I try to use tabs. I don't really care though, as long as a single file is internally consistent.

Naming Conventions

Here are the basic conventions, which are not really consistent. Not a big deal, I sometimes clean these up as I go.

  • ClassName::functionName
  • ClassName::class_variable
  • local_variable
  • ENUM_OR_CONSTANT

Commenting

I try to use Javadoc style comments on functions, especially if they're non-obvious.

I try to avoid block comments inside functions (so it's easy to block comment out an entire function).

Namespaces

Avoid polluting the project's namespace. This means no using namespace std. Instead, prefix the appropriate names with the std:: syntax (e.g. std::vector, std::string, std::min(), etc)