Coding guidelines: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(Update link to mtasa-docs)
 
(30 intermediate revisions by 10 users not shown)
Line 1: Line 1:
= Introduction =
== MTA:SA Project ==
The Multi Theft Auto: San Andreas source code is available on GitHub in the [https://github.com/multitheftauto/mtasa-blue mtasa-blue repository].


So you've decided to become a contributor to our project. Excellent! But before we can start accepting your code, there are a couple of things you should know about how we work. These are mostly guidelines and rules as to how your code should be structured and how it can be committed without upsetting any fellow contributors.
The [https://github.com/multitheftauto/mtasa-docs/blob/main/mtasa-blue/CONTRIBUTING.md CONTRIBUTING.md document] is a general guide to contributing to the project, where you will find the Coding guidelines.


= Code repository =
[[Category: Development]]
 
== Structure ==
Our code repository (SVN) is structured into number of different directories, which serve different purposes:
* '''trunk''': the current development trunk (latest but experimental)
* '''branches''': branches with groundbreaking research, radical ideas and other work-in-progress that is meant to be merged into the trunk at a later point, but also contains project milestones (which are kept away from the trunk for stability reasons)
* '''vendor''': unmodified third-party code and libraries (optionally linked to the appropriate third-party SVN repository through svn:externals)
 
== Gaining and Losing Commit access ==
Commit access is granted after patches have been submitted, and the coder has proven to be competent.  The subject matter of the patches does not matter, we are more interested in whether if you are granted commit access, you will be capable of mantaining a high standard of code and remaining cohesive with other project contributors.
 
Patches can be submitted in our [http://bugs.mtasa.com/search.php?project_id=15hide_status_id=90 Mantis Source Patches] section.  Usually commit access is gained after 2-3 patches, but this is not fixed and depends on the extent of the contributions.
 
After gaining commit access, if the contributor's commits are of a consistently low standard, or the user fails to stick to the rules, their commit access will be stripped and will be required to submit patches again.
 
=== Special circumstances ===
If you are interested in working on a large feature implementation, we do allow for special commit access on a branch basis.
 
This means we will open a branch for your large feature, so that you can work exclusively on this branch, even if you have not submitted any patches.  Examples for which this has been used in the past are the ''Unicode'' and the ''Voice'' branches, both large scale features.
 
You will of course need to prove you are a competent coder or have made progress in this feature already.  You will also have to follow all of the coding guidelines when makings commits, since your code can eventully affect the main codebase.
 
Please contact us on IRC if you are interested in opening a feature branch.
 
== Committing code ==
Keep in mind that your commits should initially be fixing or implementing existing issues on our [http://bugs.mtasa.com Bug tracker]. The [http://bugs.mtasa.com/roadmap_page.php Roadmap] is especially important since it allows contributors to track down priority issues.
 
Please follow these guidelines for all your contributions:
* Commits should be thoroughly tested when using the trunk.  Commits that 'need to be fixed later' which directly affect the state of the mod will be reverted other than in exceptional circumstances.
* If writing unstable or experimental code, a branch should be opened for each feature.  Branches should not be "personal" to each user.  This means that a branch should be created for a new feature, not for a user specific playground.
* Log messages should always give a clear indication of the content of the change, without having to look at the code at all.  Where appropriate, include the Mantis Issue number in your log message and keep your log messages consistent, e.g. '''Fixed #1234: description and notes here'''.  When using branches, the name of the branch should be quoted in the message log, e.g. '''[customanimations] Added IFP support'''.
* When committing updates to previous commits, include the previous revision number (and previous commit message if possible) in the new commit message. Doing this will help identify related commits if they merged at a later date.
 
== Ratings and comments ==
Ratings and comments are open for the public to review code and provide feedback.  Please be mature and civilised when posting comments.  Developers should try to review other contributor's commits and provide feedback as much as possible.
 
== What to code ==
Generally, developers should try to stick to the [http://bugs.mtasa.com/roadmap_page.php Roadmap] when coding.  This lists the issues required to be resolved for the next release. Of course, if you're interested in something else, feel free to experiment and submit it.
 
== Style ==
* We use 4 spaces instead of tabs.
* Hungarian notation for variable names.
float        fValue;              // Local variable
unsigned char m_ucValue;            // Class member variable
char          ms_cValue;            // Class static variable
bool          g_bCrashTwiceAnHour;  // Global variable
char*        szUsername;          // Zero terminated string
SString      strUsername;          // String
CVector      vecPosition;          // 3D Vector
* Lower camel case for variable names of types like custom structs and enums:
SSomeStruct  valueOne;
ESomeEnum    m_valueTwo;
* Function names use UpperCamelCase:
void UpperCamelCase( void )
* A space between almost everything:
int iResult = 2 + 4 * GetValue() + 123;
* A space between a function name and the open parenthesis is optional:
void OkOne ( void )
void OkTwo( void )
OkThree ();
OkFour();
* Functions with no arguments are declared and defined with ( void ), and called with ()
void MyTest( void );
void MyTest( void ) { return; }
MyTest();
* Functions and member variables of classes/structs are all lined up in neat columns:
void      FunctionOne    ( void );
void      FunctionTwo    ( void );
float      fValue;
* For anything else, follow the style of the code that already exists.

Latest revision as of 14:29, 20 July 2024

MTA:SA Project

The Multi Theft Auto: San Andreas source code is available on GitHub in the mtasa-blue repository.

The CONTRIBUTING.md document is a general guide to contributing to the project, where you will find the Coding guidelines.

Retrieved from "https://wiki.multitheftauto.com/wiki/Coding_guidelines?oldid=79927"