developer guidelines

Introduction

This is meant to be a list of accepted philosophies used when developing fife. Unfortunately these philosophies have been developed after fife development was well underway and therefore may not fully comply with them. These schools of thought described here are very important to know and follow when you are working on fife. Any fife developer should be VERY familiar with them before implementing any new features. If you notice any part of fife that does NOT comply to these philosophies please create an issue.

Git guidelines

See our working with git page.

Code should compile without warnings on a recent gcc(4.x) and at least the -Wall flag.
If you do something that breaks lots of stuff and will take some time, create your own branch.
Apart from the previous points, commit often.
The commit log message should contain a summarization of your commited changes along with the ticket number you are working on.

Input file formats

fife's accepted input file format is XML. The XML format should be used when describing data (metadata). Any new or existing functionality (like font file definitions) should also use the XML format.

Exceptions and return codes

Exceptions should only be thrown for exceptional situations. Examples of when to throw an exception are if the engine failed to create the OpenGL device context or if SDL failed to initialize. These are errors that cannot be recovered from and an exception should be thrown. In all other cases you should somehow recover from the situation. For example, if a function returns a list of instances but couldn't find any, return an empty list.

With that being said exceptions should be created and used properly. All exceptions should be derived from FIFE::Exception and should be caught by reference only.

For extra reading on exceptions here is an interesting discussion on exceptions.

Writing to the log

Logs are very a useful tool when debugging fife and they MUST be used properly. You have to use your own judgment as to when to write something to the log. The problem is that logs can become a little too verbose. As a general rule of thumb, if something unexpected happened but can be recovered from (i.e. an operation failed to complete but execution can still continue) you should write an entry in the log with a log level of WARN. If the error cannot be recovered from but doesn't warrant an exception you should use a log level of ERROR. All informational information you should use the log level of LOG. This information can include any information you deem important enough to inform the client of. An example would be how many instances were created when the map loaded.

Of course ALWAYS use the correct log module when writing to the log. They are defined in the <FIFE>/engine/core/modules.h header file.

When writing to the log you should ALWAYS use the provided log macros: