Engine Development Philosophies

From FIFE development wiki
Jump to: navigation, search

This article is part of design documentation. Design 32.png

Design documentation describes how software is implemented or is about to be implemented. It focuses on system structure (e.g. dependencies), module interactions and relevant algorithms. Concepts described in these articles should form the terminology that is used when discussing about the software that forms FIFE.

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 file a ticket and mark it as a High priority.

Coding Standards

We have a good set of coding standards that have been followed for some time. They are quite detailed and have been described in detail in the following documents:

SVN Commit Guidelines

  • Code should compile without warnings on a recent gcc(4.x) and at least the -Wall flag before you consider commiting it. It's ok to commit something with some warnings if you are still working on it and it's not finished yet.
  • Don't commit something that doesn't compile.
  • 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.
  • Set SVN:eol-style to "native" for the following file types:
    • .h, .hpp
    • .c, .cpp
    • .py
    • .txt
    • .xml
    • .dot
  • Set SVN:executable to "*" only for Python scripts that *nix users should be able to run directly. Add a shebang to these scripts and only to these scripts as well.
  • Set SVN:ignore for the following file types:
    • .dll
    • .exe
    • .pyc
    • thumbs.db
  • The commit log message should contain a summarization of your commited changes along with the ticket number you are working on.
  • Check your changes before commiting with svn status (command line client) / Check for modifications (TortoiseSVN).
  • Always test your code before your commit. Testing has been tried to make as easy as possible. At minimum, run all of our demos along with the map editor to see if your code really works as part of the system.

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. Existing input file types include:

  • Font definitions (currently not XML)
  • Map
  • Object
  • Animation
  • Pychan widget layout and styles

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:

  • FL_DBG(module, msg)
  • FL_LOG(module, msg)
  • FL_WARN(module, msg)
  • FL_ERR(module, msg)
  • FL_PANIC(module, msg)

Dependencies

FIFE depends on a large number of 3rd party libraries. Unfortunately not all of the 3rd party libraries are still in active development so we have some first hand experience with this. You should try to not introduce new dependencies whenever possible by writing your own code to accomplish what the 3rd party library can do. If it's deemed to be too time consuming to roll your own code and you must use a 3rd party library you should ensure it meets the following guidelines:

  1. Supported on most platforms (Windows, Linux and Mac OSX at a minimum)
  2. Widely used by other projects and has an active community
  3. Available to download as a package for most platforms
  4. Has been in active development for a number of years
  5. License is compatible with FIFE!