Important Github Rules - To ALL people who have write access

If you have a question about the git repository and the code, or if you have code to propose then please post in this forum.
Do not post request here.
Post Reply
wololo
Site Admin
Posts: 3727
Joined: Wed Oct 15, 2008 12:42 am
Location: Japan

Important Github Rules - To ALL people who have write access

Post by wololo » Mon Jun 08, 2009 1:39 pm

The number of people who have write access to the SVN is growing, which is good, but also brings confusion from time to time. This post is a set of rules that we should follow, so that the game can go in the correct direction. I will update it as necessary.

REGISTER TO OUR MAILING LIST
request a registration to: http://groups.google.com/group/wagic-dev. This needs to be moderator approved, so it might take a few days.
(Optional) You can also register to : http://groups.google.com/group/wagic-svn which will give you info every time a comment or a new revision is posted in the SVN. This one doesn't need any kind of approval.


TEST YOUR CHANGES
1 - BEFORE committing a change to git, run the Test Suite. If you don't know how to run the Test suite, ask me. It requires either Linux or Windows.
- the results of the tests are in USer/test/results.html
- If a test in the test suite fails, try to run the test suite a second time. There's a race condition that makes some tests fail if the framerate slows down. If a test fails twice, there's a high chance it's a real bug.
2 - If you didn't follow rule number 1, and your change breaks a test, be ready to hear me shout and scream.
3 - If you add a new card that you are not confident will work, test it. NO MORE "not tested, but I guess it should work" messages in the SVN, please.
4 - Don't commit half finished stuff in the SVN. The latest revision of the SVN should always be in a state good enough for it to be a "candidate for release". If you have huge changes in progress, make local backups on your hard drive, or create a branch in the SVN.

CODING STYLE
These rules are not "must" but "nice to have". People who don't respect them won't be shot in the head, people who respect them are cool guys.
  • We use the Unix encoding for carriage returns. If you use windows, there's probably an option for that in your editor. Visual Studio will usually ask you when there's a strange file. Always reply "Unix"
  • 4 space indentation. Don't use tabs for indentation, use spaces. One tab = 4 spaces. There is a setting for this in Visual Studio.
  • the "=" sign should be separated by spaces. "a = 1;" is good. "a=1;" is not. "a= 1;" and "a =1;" are even worse.
  • curly braces go on a new line

    Code: Select all

    if (foo)
    {
        bar();
        stuff();
    }
    
  • If a scope contains only one line, it is ok to omit the curly braces. It is fine to have them too. The following are all ok, use your judgment here:

    Code: Select all

    if (foo)
    {
        bar();
    }
    

    Code: Select all

    if (foo)
        bar();
    

    Code: Select all

    if (foo) bar();
    
  • parameters spacing: no space between function name and parenthesis, space after a comma separating parameters:

    Code: Select all

    int foo(int a, int b)
    this.foo(a, b);
  • Avoid to nest if/while/for too much. As a rule of thumb, If you have more than 3 "nested loops" levels, there is probably a better way
  • As a consequence of the rule above, we suggest to return early:

    Code: Select all

    if (not_applicable) return; // And don't care any more
  • in header (.h) files, use the following order: private, protected, public > Attributes then methods, group them by "goal/semantics" rather than alphabetically. No specific rule for .cpp files

    Code: Select all

    MyClass
    {
        protected:
            int mHeight;
            int mWidth;
    
            float stuff;
    
            int foo();
    
        public:
            int mPublicVar;
    
            MyClass(int stuff);
    };
    
  • Variable naming: we use camelCase and a simple prefix for global variables and attributes: gGlobal, mAttribute, noSpecificRuleForLocalVars.If possible we want to avoid global variables. First letter is lowercase.
  • Variable Naming: Function names and class declarations should be capitalized, whereas objects/variables shouldn't.
  • Variable naming: on top of the above rules, For globals, constants, and class attributes, use full words, except in the rare case where an abbreviation would be more canonical and easier to understand. For local variables, use your best judgment and a balance between readability and efficiency.
  • Constants: We are still debating between UPPERCASE_CONSTANT and kConstant
  • no magic numbers, use enum or define instead:

    Code: Select all

    if (Constants::MAGIC_NUMBER == myVariable)
    is good,

    Code: Select all

    if (55 == myVariable)
    is not.
  • We love comments in the code, as long as they don't state the obvious
    we don't need

    Code: Select all

    int getHeight(); //gets the Height
    we love

    Code: Select all

    superHack(); // There's a bug with some cards that require to call this hack, see http://code.google.com/p/wagic/issues/detail?id=123
    
You can discuss issues with git in this thread. Not technical issues, but "organization" issues.

Post Reply