Skip to content

Tech Design Document

Jump to bottom
Sergi PR edited this page Apr 19, 2018 · 35 revisions

Code Style

Why should we care about code styles? Isn’t it enough that our code works? Well there are a couple of reasons to care about our code styles.

The first one is consistency. Any large code base with multiple team members should look as if only one programmer wrote it. As a consequence source code revision will be more comfortable.

The second reason is better code readability. If all the programmers follow the same style, the code will be easier to read, which is key.

Our code is going to be based on the following guidelines:

Naming conventions

Every name should attempt to describe the purpose of the piece of code, what it does. If it is too hard to describe it with a short name, it is suggested to divide the code into more specific parts. This is specially important in functions.

Here is an interesting article about naming conventions to read.

Names have to reveal intentions

Bad code example:

int d;
// elapsed time in days
int ds;
int dsm;
int faid;

Good code example:

int elapsed-time-in-days;
int days-since-creation;
int days-since-modification;
int file-age-in-days;

How specific code items must be named:

Variables

Variables will be written following the snake_case (underscore between words) style:

char       character = 0;
int        integer = 0;
float      floating_point = 0.0f;
double     long_double = 0;
uint       undigned_int = 0;
bool       boolean = false;
ENUM_TYPE  e = ENUM_TYPE::null;
pointer*   p = nullptr;
SDL_Rect   r = NULLRECT;
SDL_Color  co = NULLCOLOR;
iPoint     ip = NULLPOINT:
fPoint     fp = NULLPOINT;

Enums

Enums names will also follow the snake_case style but in all caps:

While enum items will be written in all caps. It is mandatory to include a DEFAULT (or NULL) variable corresponding to 0 for initialization.

Defines

Defines will be written in all caps with an underscore between words:

#define GLOBAL_SOMETHING

Class Defines must begin and end with __.

#ifndef __CLASS_NAME__
#define __CLASS_NAME__
    [...]
#endif

Structs

Structs will be written following the snake_case style: Variables inside structs should follow the standard variable style.

struct example_struct;

Classes

Classes will be written following the PascalCase (Caps between words) style:

class RyuCharacter;

If the class is a module it must be prefixed with md

class mdWindow;

Functions

Functions will be written following the camelCase style:

mdAudioEngine::playSound(bool is_enabled){
    [...]
}

Files

Files will be written following the kebab-case (hyphen between words) style:

To distinguish between the progress of files, they must use the following code:

  • OG = Original file
  • WK = Work in progress
  • QA = Needs quality assurance
  • PR = It's a prototype
  • Final = Finished

Example:

art-sheet-OG.png
art-sheet-WK.png
art-sheet-QA.png
art-sheet-PR.png
art-sheet-Final.png

Branches

Branches will be written following the kebab-case style:

good-branch-name

Variable initialization

All variables must be initialized unless there is a very strong reason not to do so. This is especially important with pointers. There are no excuses for not initializing a pointer with nullptr.

Comments

Code should be written focusing on making it easy to understand without the need of comments. Nevertheless, comments are always helpful and is it advised to use them to clarify or explain as much as needed. It is recommended to use them in the header of functions as the comment will be displayed when hovering over the function in visual studio.

Comments should be either above or next to the line that wants to be commented and using the // method.

//This is a valid comment
void mdExampleModule::exampleFunction (void example_input) {
    [...] //This is also a valid comment
}

Braces

Opening braces must go in the same line than the function/loop/conditional and closing braces must be placed in a new line.

void mdExampleModule::exampleFunction (void example_input) {
    [...]
}

Branching policy

We will be following the Gitflow workflow in terms of maintaining our repository, with a few modifications. This means we will have two main types of branches:

The main branches

The repository will pivot on two branches that will never be deleted or merged into another branch:

  • master
  • develop

The master branch must reflect a production ready state, meaning all pushes to the master branch can and will result in a release.

The develop branch will contain the latest delivered development changes for the next release.

Supporting branches

Gitflow uses a variety of supporting branches to aid parallel development between team members as well as ease the tracking of features. Unlike the main branches, these branches always have a limited life time, since they will be removed eventually. They are categorized in three groups:

  • Feature branches
  • Release branches
  • Hotfix branches

Feature branches

Will branch off from:
develop
Must merge back to:
develop
Naming convention:
my-feature-name (master, develop, release-* and hotfix-* are not allowed)

Feature branches are used to develop new features for the next or a future release. When starting development of a feature, the target release in which this feature will be does not need to be known. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the next release) or discarded (in case the feature is cut from the game, or if it was an unsucessful experiment).

Merging procedure:
To merge a feature branch first a pull request must be made inside the GitHub repository. Once the pull request is made, whoever is reponsible for accepting it must check first if that feature is for the next release (if not it must remain unmerged until the appropiate release) and then merge the develop branch into the feature branch to check for conflicts and bugs.

git checkout my-feature-branch
git pull
git merge --no-commit develop

Once the code has been checked and all conflicts have been fixed, then the following commit can be created:

git commit -a -m "Preparing branch for merge with develop"
git push -u origin my-feature-branch

Then the branch may be merged to develop via GitHub pull request and subsequently deleted afterwards.

Release branches

Will branch off from:
develop
Must merge back to:
develop and master
Naming convention:
release-* (* being release version)

Release branches are used to prepare the next release, as well as some final preparations and some minor bug-fixing. These will be created some days before the release date and will be created once develop has all features for the next release, thus freeing develop to receive features for the next release.

Merging procedure:
To merge a release branch first a pull request must be made inside the GitHub repository to merge into master. Once the pull request is made, whoever is reponsible for accepting it must check everything is in order in the branch and then accept the pull request and merge into master, once that is done, then the branch must be merged into develop

git checkout develop
git pull
git merge --no-commit release-*

Once the code has been checked and all conflicts have been fixed, then the following commit can be created:

git commit -a -m "Merging release-* into develop"
git push -u origin develop

Then the branch may be deleted through GitHub or through git like so

git push -d origin feature-*
git branch -d feature-*

Hotfix branches

Will branch off from:
master
Must merge back to:
develop and master
Naming convention:
hotfix-* (* being hotfix version)

Hotfix branches are created when a critical bug is detected in the current release and are used to fix said bug quickly and push a new release.

Merging procedure:
To merge a hotfix branch first a pull request must be made inside the GitHub repository to merge into master. Once the pull request is made, whoever is reponsible for accepting it must check everything is in order in the branch and then accept the pull request and merge into master, once that is done, then the branch must be merged into develop

git checkout develop
git pull
git merge --no-commit hotfix-*

Once the code has been checked and all conflicts have been fixed, then the following commit can be created:

git commit -a -m "Merging hotfix-* into develop"
git push -u origin develop

Then the branch may be deleted through GitHub or through git like so

git push -d origin hotfix-*
git branch -d hotfix-*

UML

You can check our project's UML diagram over here.

Version list

  • v0.1 - Code backbone
First basic collisions  
Start menu  
Basic attacks of the Warrior
  • v0.2 - First combat
1vs1 combat (with hitstun, blockstun, projectiles and a rough block)
First UI sketch
Options and credits menus
First SFX, music
Adding more sprites.
  • v0.3 - Swap mechanic and 2v2
2vs2 basic combat
Introduction of the swap mechanic
Character selection screen
More special moves for the Warrior
Paladin sprites
More UI features, such as HP, time, swap CD...
  • v0.4 - 2v2 Combat
Finalize the 2v2 combat mechanics
  • v0.5 - Vertical Slice
All of the warrior's special moves implemented
Item system
Warrior's special items, the general ones
Particle system
  • v0.6 - Finalization of the item system
Polish of the v0.5 features
Item system finalization
  • v0.7 - New characters
Implementation of paladin/wizard
  • v0.8 - Finalization
All the characters included,
Full UI implemented
Adding the map features.

Development freeze

  • v0.9 - Alpha
Gameplay balancing
General polish
Bugtesting
  • v1.0 - Gold
Bug free version
Final mechanics

Target Hardware

Win64 (x64_86 architecture)
RAM: 8.00 GB
Processor: Intel Core i7-3770 3.4GHz
Graphic Card: NVIDIA Quadro 600 1GB DDR3
Running Windows 7 or higher.

Performance budget

The game should be running at 60 frames per second.

  • Game starting and loading: 6000 ms.
  • Map printing: 6 - 10 ms.
  • Input handling and printing characters: 1 ms.
  • Attacks logic and printing: 0.5 ms.
  • UI: 3 ms.
  • Audio: 1 ms

External libraries

We will use as external libraries:

SDL: For graphics drawing, reproducing sound and time control.

Pugixml: To be able to iterate fast by reading important values from an xml file instead of having to recompile the project.

Box2D: To have a good collision detection.

Delivery Method

Every milestone will be released using AppVeyor to automatically publish a release when pushes to the master branch are made. All releases will be inside a .zip containing a folder with the executable, needed dlls as well as the binaries needed for the game.

← Previous Page | Home | Next Page →

Clone this wiki locally