Developers

 
 
All of our software is open source and we would happily add new code, features and fixes from other developers. We have created this page to outline some information for developers and the standards used in our projects. If you have any questions, comments or complaints about these development guidelines please let us know.

 
Definitions
  • Officially Released Code: Code meets all requirements and is released in all official releases.
  • Development Released Code: Completed code added to the CVS codebase, but missing some criteria (see below) required for movement to "official" status. This code will remain in the codebase but will not be included in official releases.

Contributing to a project:

When adding sourcecode or modifying existing sourcecode we ask you follow these guidelines to ensure code enters the official codebase:
  1. Did it break : After adding or modifying sourcecode run the unit test suite for the project. Please make sure that the changes to not break any of the existing code.
  2. Is it broken: New code should be thoroughly tested. At the very least, the code should be completely tested using unit tests.
  3. Is it Documented
    • All classes should have a header similar to the existing classes (name of file, name of package, license information)
    • All classes should have a JAVADOC comment describing the purpose of the class, name of original author and the first version of the code the class appeared in.
    • All methods should have a JAVADOC comment describing the purpose of the method, name of all authors who have worked on the method, the first version of the code the method appeared in and a description of the method parameters and return values.
    • Implementations of non-trivial algorithms should have a reference to a document describing the algorithm included in the JAVADOC somewhere.
  4. Is it consistent: If your changes modify the method signatures of public method, move classes, remove methods, or otherwise may have an impact on how the software is used by external classes and programs then the changes and expected benefits should be made available for discussion with other developers.
  5. Is it clean: Does your coding follow general best practices? Are methods and variables appropriately named, is the code free of "smells", do you make use of existing code, is the code maintainable?
  6. Is it arranged properly: All core code should be in the JIFSA, and any domain specific code should be in a different package. This helps make the central JIFSA framework reusable by any implementation. For example, all code related to imitating RoboCup simulated soccer agents is in RCSImitate, not JIFSA.
What if one (or more) conditions are not met:
  1. The code will not be considered complete enough for official releases and will not be included in released versions of the software.
  2. The code will remain in CVS and can be updated to meet these conditions at a later date.
  3. Code that does not meet these conditions can be perfect projects for students or novice developers. This can provide excellent experience in unit testing, documentations, refactoring and many other software development areas. Often the original developers were unable to complete their code due to time constraints and would likely be happy if you would complete it for them. This also helps to ensure all submitted code is of a high enough quality so it can be included in official releases.