tyler.durden
/
notepad-plus-plus
mirror of https://github.com/notepad-plus-plus/notepad-plus-plus.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve readability of CONTRIBUTING.md (closes #513)

This commit is contained in:
Ricardo 2015-07-16 17:29:09 -03:00 committed by Damien GERARD
parent 1b8bdfb6e5
commit 428b4f1596
1 changed files with 189 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

369
CONTRIBUTING.md
View File

@ -4,252 +4,261 @@ Your pull requests are welcome; however, they may not be accepted for various re
## Before you contribute ## Before you contribute
All Pull Requests, except for translations and user documentation, need to be All Pull Requests, except for translations and user documentation, need to be attached to a issue on GitHub. For Pull Requests regarding enhancements and questions, the issue must first be approved by one of project's administrators before being merged into the project. An approved issue will have the label `Accepted`. For issues that have not been accepted, you may request to be assigned to that issue.
attached to a issue on GitHub. For Pull Requests regarding enhancements and questions,
the issue must first be approved by one of project's administrators before being
merged into the project. An approved issue will have the label `Accepted`. For issues
that have not been accepted, you may request to be assigned to that issue.
Opening a issue beforehand allows the adminstrators and the communitiy to discuss Opening a issue beforehand allows the administrators and the community to discuss bugs and enhancements before work begins, preventing wasted effort.
bugs and enhancements before work begins, preventing wasted effort.
## Guidelines for pull requests
## Guidelines for pull requests:
1. Respect Notepad++ coding style. 1. Respect Notepad++ coding style.
2. Make a single change per commit. 2. Make a single change per commit.
3. Make your modification compact - don't reformat source code in your request. It makes code review more difficult. 3. Make your modification compact - don't reformat source code in your request. It makes code review more difficult.
4. PR of reformatting (changing of ws/TAB, line endings or coding style) of source code won't be accepted. Use issue trackers for your request instead. 4. PR of reformatting (changing of ws/TAB, line endings or coding style) of source code won't be accepted. Use issue trackers for your request instead.
In short: The easier the code review is, the better the chance your pull request will get accepted. In short: The easier the code review is, the better the chance your pull request will get accepted.
## Coding style
![stay clean](https://notepad-plus-plus.org/assets/images/good-bad-practice.jpg)
##Coding style:
<img src="https://notepad-plus-plus.org/assets/images/good-bad-practice.jpg">
####GENERAL #### GENERAL
* Do not use Java-like braces: 1. ##### Do not use Java-like braces.
GOOD: * ###### Good:
```c ```cpp
if () if ()
{ {
// Do something // Do something
} }
``` ```
BAD:
```c * ###### Bad:
if () { ```cpp
// Do something if () {
} // Do something
``` }
* Use tabs instead of whitespaces (we usually set our editors to 4 ```
whitespaces for 1 tab, but the choice is up to you)
1. ##### Use tabs instead of white-spaces (we usually set our editors to 4 white-spaces for 1 tab, but the choice is up to you).
* Always leave one space before and after binary and ternary operators 1. ##### Always leave one space before and after binary and ternary operators.
Only leave one space after semi-colons in "for" statements.
GOOD: * ###### Good:
```c ```cpp
if (10 == a && 42 == b) if (10 == a && 42 == b)
``` ```
BAD:
```c
if (a==10&&b==42)
```
GOOD:
```c
for (int i = 0; i != 10; ++i)
```
BAD:
```c
for(int i=0;i<10;++i)
```
* Keywords are not function calls.
Function names are not separated from the first parenthesis:
GOOD: * ###### Bad:
```c ```cpp
if (a==10&&b==42)
```
1. ##### Only leave one space after semi-colons in "for" statements.
* ###### Good:
```cpp
for (int i = 0; i != 10; ++i)
```
* ###### Bad:
```cpp
for(int i=0;i<10;++i)
```
1. <h5>Keywords are not function calls;<br>
Function names are not separated from the first parenthesis.</h5>
* ###### Good:
```cpp
foo(); foo();
myObject.foo(24); myObject.foo(24);
``` ```
BAD:
```c
foo ();
```
* Keywords are separated from the first parenthesis by one space :
GOOD: * ###### Bad:
```c ```cpp
foo ();
```
1. ##### Keywords are separated from the first parenthesis by one space.
* ###### Good:
```cpp
if (true) if (true)
while (true) while (true)
``` ```
BAD:
```c
if(myCondition)
```
* Use the following indenting for "switch" statements * ###### Bad:
```c ```cpp
if(myCondition)
```
1. ##### Use the following indenting for "switch" statements:
```cpp
switch (test) switch (test)
{ {
case 1: case 1:
{ {
// Do something // Do something
break; break;
} }
default: default:
// Do something else // Do something else
} // No semi-colon here } // No semi-colon here
``` ```
* Avoid magic numbers 1. ##### Avoid magic numbers.
BAD: * ###### Good:
```c ```cpp
while (lifeTheUniverseAndEverything != 42) if (foo < I_CAN_PUSH_ON_THE_RED_BUTTON)
lifeTheUniverseAndEverything = buildMorePowerfulComputerForTheAnswer(); startThermoNuclearWar();
``` ```
GOOD:
```c
if (foo < I_CAN_PUSH_ON_THE_RED_BUTTON)
startThermoNuclearWar();
```
* Prefer enums for integer constants * ###### Bad:
```cpp
while (lifeTheUniverseAndEverything != 42)
lifeTheUniverseAndEverything = buildMorePowerfulComputerForTheAnswer();
```
* Use initialization with curly braces 1. ##### Prefer enums for integer constants.
GOOD: 1. ##### Use initialization with curly braces.
```c
MyClass instance{10.4};
```
BAD:
```c
MyClass instance(10.4);
```
* Always use `empty()` for testing if a string is empty or not * ###### Good:
```cpp
MyClass instance{10.4};
```
GOOD: * ###### Bad:
```c ```cpp
if (not string.empty()) MyClass instance(10.4);
... ```
```
BAD: 1. ##### Always use `empty()` for testing if a string is empty or not.
```c
if (string != "") * ###### Good:
... ```cpp
``` if (not string.empty())
...
```
* ###### Bad:
```cpp
if (string != "")
...
```
####NAMING CONVENTIONS #### NAMING CONVENTIONS
* Classes (camel case) : 1. ##### Classes (camel case)
GOOD: * ###### Good:
```c ```cpp
class IAmAClass class IAmAClass
{}; {};
``` ```
BAD:
```c
class iAmClass
{};
class I_am_class
{};
```
* methods (camel case + begins with a lower case) * ###### Bad:
method parameters (camel case + begins with a lower case) ```cpp
class iAmClass
{};
class I_am_class
{};
```
GOOD: 1. <h5>methods (camel case + begins with a lower case)<br>
```c method parameters (camel case + begins with a lower case)</h5>
```cpp
void myMethod(uint myVeryLongParameter); void myMethod(uint myVeryLongParameter);
``` ```
* member variables
Any member variable name of class/struct should be preceded by an underscore 1. <h5>member variables<br>
```c Any member variable name of class/struct should be preceded by an underscore.</h5>
```cpp
public: public:
int _publicAttribute; int _publicAttribute;
private: private:
int _pPrivateAttribute; int _pPrivateAttribute;
float _pAccount; float _pAccount;
``` ```
* Always prefer a variable name that describes what the variable is used for 1. ##### Always prefer a variable name that describes what the variable is used for.
GOOD: * ###### Good:
```c ```cpp
if (hours < 24 && minutes < 60 && seconds < 60) if (hours < 24 && minutes < 60 && seconds < 60)
``` ```
BAD:
```c
if (a < 24 && b < 60 && c < 60)
```
####COMMENTS * ###### Bad:
```cpp
* Use C++ comment line style than c comment style if (a < 24 && b < 60 && c < 60)
```
GOOD:
```
// Two lines comment
// Use still C++ comment line style
```
BAD:
```
/*
Please don't piss me off with that
*/
```
####BEST PRACTICES
* Use C++11/14 whenever it is possible #### COMMENTS
* Use C++11 member initialization feature whenever it is possible 1. ##### Use C++ comment line style than C comment style.
```c
class Foo
{
int value = 0;
};
```
* Prefer this form : * ###### Good:
```c ```
++i // Two lines comment
``` // Use still C++ comment line style
to ```
```c
i++ * ###### Bad:
``` ```
(It does not change anything for builtin types but it would bring consistency) /*
Please don't piss me off with that
*/
```
* Avoid using pointers. Prefer references. You might need the variable to
be assigned a NULL value: in this case the NULL value has semantics and must
be checked. Wherever possible, use a SmartPtr instead of old-school pointers.
* Avoid using new if you can use automatic variable. #### BEST PRACTICES
However, avoid `shared_ptr` as much as possible. Prefer `unique_ptr` instead.
* Don't place any "using namespace" directives in headers 1. ##### Use C++11/14 whenever it is possible
* Compile time is without incidence. Increasing compile time to reduce execution 1. ##### Use C++11 member initialization feature whenever it is possible
time is encouraged.
* Code legibility and length is less important than easy and fast end-user experience. ```cpp
class Foo
{
int value = 0;
};
```
1. ##### Prefer this form:
```cpp
++i
```
**to:**
```cpp
i++
```
(It does not change anything for built-in types but it would bring consistency)
1. ##### Avoid using pointers. Prefer references. You might need the variable to be assigned a NULL value: in this case the NULL value has semantics and must be checked. Wherever possible, use a SmartPtr instead of old-school pointers.
1. ##### Avoid using new if you can use automatic variable. However, avoid `shared_ptr` as much as possible. Prefer `unique_ptr` instead.
1. ##### Don't place any "using namespace" directives in headers.
1. ##### Compile time is without incidence. Increasing compile time to reduce execution time is encouraged.
1. ##### Code legibility and length is less important than easy and fast end-user experience.