archive/dolphin
1
0
Fork 0
mirror of https://github.com/dolphin-emu/dolphin.git synced 2024-09-20 03:11:51 +02:00
Code Issues Projects Releases Packages Wiki Activity

Contributing.md: Minor re-organization of headings

Browse source 
This gives headings consistent link references that won't arbitrarily
change if the text representing it does, which makes for better
organization. This is also less error-prone when it comes to specifying
links in the presence of two headings with the same text content, but
under different sections.

This also treats each section and sub-section such that they all have
their own dividers.
This commit is contained in:
Lioncash 2017-03-04 20:44:11 -05:00
parent c2594695b8
commit 0fa8d6b49b
1 changed files with 42 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

72
Contributing.md
View file

@ -1,26 +1,23 @@
# Dolphin Coding Style & Licensing # <a name="main-heading"></a>Dolphin Coding Style & Licensing
If you make any contributions to Dolphin after December 1st, 2014, you are agreeing that any code you have contributed will be licensed under the GNU GPL version 2 (or any later version). If you make any contributions to Dolphin after December 1st, 2014, you are agreeing that any code you have contributed will be licensed under the GNU GPL version 2 (or any later version).
## Coding Style # <a name="main-section-overview"></a>Main sections
- [Introduction] (#introduction) - [Introduction](#introduction)
- [Checking and fixing formatting issues](#checking-and-fixing-formatting-issues) - [C++ coding style and formatting](#cpp-coding-style-and-formatting)
- [Styling and formatting] (#styling-and-formatting) - [C++ code-specific guidelines](#cpp-code-specific-guidelines)
- [General] (#general) - [Android and Java](#android-and-java)
- [Naming] (#naming)
- [Conditionals] (#conditionals)
- [Classes and Structs] (#classes-and-structs)
- [Code specific] (#code-specific)
- [General] (#general-1)
- [Headers] (#headers)
- [Loops] (#loops)
- [Functions] (#functions)
- [Classes and Structs] (#classes-and-structs-1)
- [Java] (#java)
## Introduction # <a name="introduction"></a>Introduction
Summary:
- [Aims](#intro-aims)
- [Checking and fixing formatting issues](#intro-formatting-issues)
## <a name="intro-aims"></a>Aims
This guide is for developers who wish to contribute to the Dolphin codebase. It will detail how to properly style and format code to fit this project. This guide also offers suggestions on specific functions and other varia that may be used in code. This guide is for developers who wish to contribute to the Dolphin codebase. It will detail how to properly style and format code to fit this project. This guide also offers suggestions on specific functions and other varia that may be used in code.
@ -29,7 +26,7 @@ Following this guide and formatting your code as detailed will likely get your p
This project uses clang-format (stable branch) to check for common style issues. In case of conflicts between this guide and clang-format rules, the latter should be followed instead of this guide. This project uses clang-format (stable branch) to check for common style issues. In case of conflicts between this guide and clang-format rules, the latter should be followed instead of this guide.
### Checking and fixing formatting issues ## <a name="intro-formatting-issues"></a>Checking and fixing formatting issues
In most cases, clang-format can and **should** be used to automatically reformat code and solve most formatting issues. In most cases, clang-format can and **should** be used to automatically reformat code and solve most formatting issues.
@ -52,9 +49,16 @@ In most cases, clang-format can and **should** be used to automatically reformat
echo '/Source/Core/**/*.mm filter=clang_format' >> .git/info/attributes echo '/Source/Core/**/*.mm filter=clang_format' >> .git/info/attributes
``` ```
## Styling and formatting # <a name="cpp-coding-style-and-formatting"></a>C++ coding style and formatting
### General Summary:
- [General](#cpp-style-general)
- [Naming](#cpp-style-naming)
- [Conditionals](#cpp-style-conditionals)
- [Classes and structs](#cpp-style-classes-and-structs)
## <a name="cpp-style-general"></a>General
- Try to limit lines of code to a maximum of 100 characters. - Try to limit lines of code to a maximum of 100 characters.
- Note that this does not mean you should try and use all 100 characters every time you have the chance. Typically with well formatted code, you normally shouldn't hit a line count of anything over 80 or 90 characters. - Note that this does not mean you should try and use all 100 characters every time you have the chance. Typically with well formatted code, you normally shouldn't hit a line count of anything over 80 or 90 characters.
- The indentation style we use is 2 spaces per level. - The indentation style we use is 2 spaces per level.
@ -80,7 +84,7 @@ In most cases, clang-format can and **should** be used to automatically reformat
while (var != 0) var--; while (var != 0) var--;
``` ```
### Naming ## <a name="cpp-style-naming"></a>Naming
- All class, enum, function, and struct names should be in upper CamelCase. If the name contains an abbreviation uppercase it. - All class, enum, function, and struct names should be in upper CamelCase. If the name contains an abbreviation uppercase it.
- `class SomeClassName` - `class SomeClassName`
- `enum IPCCommandType` - `enum IPCCommandType`
@ -94,7 +98,7 @@ In most cases, clang-format can and **should** be used to automatically reformat
- Class variables – `m_` - Class variables – `m_`
- Static variables – `s_` - Static variables – `s_`
### Conditionals ## <a name="cpp-style-conditionals"></a>Conditionals
- Do not leave `else` or `else if` conditions dangling unless the `if` condition lacks braces. - Do not leave `else` or `else if` conditions dangling unless the `if` condition lacks braces.
- Yes: - Yes:
@ -128,7 +132,7 @@ In most cases, clang-format can and **should** be used to automatically reformat
``` ```
### Classes and Structs ## <a name="cpp-style-classes-and-structs"></a>Classes and structs
- If making a [POD](http://en.wikipedia.org/wiki/Plain_Old_Data_Structures) type, use a `struct` for this. Use a `class` otherwise. - If making a [POD](http://en.wikipedia.org/wiki/Plain_Old_Data_Structures) type, use a `struct` for this. Use a `class` otherwise.
- Class layout should be in the order, `public`, `protected`, and then `private`. - Class layout should be in the order, `public`, `protected`, and then `private`.
- If one or more of these sections are not needed, then simply don't include them. - If one or more of these sections are not needed, then simply don't include them.
@ -154,9 +158,17 @@ private:
}; };
``` ```
## Code Specific # <a name="cpp-code-specific-guidelines"></a>C++ code-specific guidelines
### General Summary:
- [General](#cpp-code-general)
- [Headers](#cpp-code-headers)
- [Loops](#cpp-code-loops)
- [Functions](#cpp-code-functions)
- [Classes and Structs](#cpp-code-classes-and-structs)
## <a name="cpp-code-general"></a>General
- The codebase currently uses C++14. - The codebase currently uses C++14.
- Use the [nullptr](http://en.cppreference.com/w/cpp/language/nullptr) type over the macro `NULL`. - Use the [nullptr](http://en.cppreference.com/w/cpp/language/nullptr) type over the macro `NULL`.
- If a [range-based for loop](http://en.cppreference.com/w/cpp/language/range-for) can be used instead of container iterators, use it. - If a [range-based for loop](http://en.cppreference.com/w/cpp/language/range-for) can be used instead of container iterators, use it.
@ -167,7 +179,7 @@ private:
- Do not use `using namespace [x];` in headers. Try not to use it at all if you can. - Do not use `using namespace [x];` in headers. Try not to use it at all if you can.
- The preferred form of the increment and decrement operator in for-loops is prefix-form (e.g. `++var`). - The preferred form of the increment and decrement operator in for-loops is prefix-form (e.g. `++var`).
### Headers ## <a name="cpp-code-headers"></a>Headers
- If a header is not necessary in a certain source file, remove them. - If a header is not necessary in a certain source file, remove them.
- If you find duplicate includes of a certain header, remove it. - If you find duplicate includes of a certain header, remove it.
- When declaring includes in a source file, make sure they follow the given pattern: - When declaring includes in a source file, make sure they follow the given pattern:
@ -179,7 +191,7 @@ private:
- Project source file headers should be included in a way that is relative to the `[Dolphin Root]/Source/Core` directory. - Project source file headers should be included in a way that is relative to the `[Dolphin Root]/Source/Core` directory.
- This project uses `#pragma once` as header guards. - This project uses `#pragma once` as header guards.
### Loops ## <a name="cpp-code-loops"></a>Loops
- If an infinite loop is required, do not use `for (;;)`, use `while (true)`. - If an infinite loop is required, do not use `for (;;)`, use `while (true)`.
- Empty-bodied loops should use braces after their header, not a semicolon. - Empty-bodied loops should use braces after their header, not a semicolon.
- Yes: `while (condition) {}` - Yes: `while (condition) {}`
@ -192,7 +204,7 @@ private:
} while (false); } while (false);
``` ```
### Functions ## <a name="cpp-code-functions"></a>Functions
- If a function parameter is a pointer or reference and its value or data isn't intended to be changed, please mark that parameter as `const`. - If a function parameter is a pointer or reference and its value or data isn't intended to be changed, please mark that parameter as `const`.
- Functions that specifically modify their parameters should have the respective parameter(s) marked as a pointer so that the variables being modified are syntaxically obvious. - Functions that specifically modify their parameters should have the respective parameter(s) marked as a pointer so that the variables being modified are syntaxically obvious.
- What not to do: - What not to do:
@ -245,7 +257,7 @@ private:
}; };
``` ```
### Classes and Structs ## <a name="cpp-code-classes-and-structs"></a>Classes and structs
- Classes and structs that are not intended to be extended through inheritance should be marked with the `final` specifier. - Classes and structs that are not intended to be extended through inheritance should be marked with the `final` specifier.
```c++ ```c++
@ -255,6 +267,6 @@ private:
}; };
``` ```
## Java # <a name="android-and-java"></a>Android and Java
The Android project is currently written in Java. If you are using Android Studio to contribute, you can import the project's code style from `code-style-java.jar`, located in `[Dolphin Root]/Source/Android`. Please organize imports before committing. The Android project is currently written in Java. If you are using Android Studio to contribute, you can import the project's code style from `code-style-java.jar`, located in `[Dolphin Root]/Source/Android`. Please organize imports before committing.