Skip to content

Latest commit

 

History

History
139 lines (109 loc) · 3.79 KB

CONTRIBUTING.md

File metadata and controls

139 lines (109 loc) · 3.79 KB
Raw

Contributing to ExplorerListView

The following is a set of guidelines for contributing to the ExplorerListView project. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table Of Contents

Styleguides

Styleguides

Git Commit Messages

  • Write them in English. It does not have to be perfect.
  • Ask yourself whether after 6 months you or anybody else will still be able to understand what has been changed and why it has been changed.
  • If external information (e.g. documentation at MSDN or threads at StackOverflow) has been important to your commit, link it.

C++ Styleguide

In most cases we follow the style suggested by the ECMA-334 standard.

(1) Terminology:

  • raising an event means preparing its sending to the connected clients
  • firing an event means sending it to all connected clients

(2) Names

  • macros and constants: Upper Case (MACRO)
  • functions, typedefs, structs: Pascal Case (MyMethod)
  • variables: Camel Case (myVariable)
  • use self-explanatory names

(3) Prefixes

  • interfaces - I
  • HANDLE - h
  • pointer - p
  • pointer to a function - pfn
  • No Hungarian notation! (except above exceptions)

(4) Indentation

  • mulit-line instructions: 4 white spaces
  • trailing comments: 5 white spaces
  • else: 1 tab
  • brackets don't get indented

(5) Comments

  • multi-line comments: /* */ /* This is a sample. The second line is indented using spaces. */
  • single-line comments: //
  • trailing comments: //
  • inline comments: /* */
  • consider commenting closing scope brackets } if the corresponding open one is located many lines before
  • TODO for optional improvements that may be useful
  • HACK for ugly code
  • UNDONE for incomplete implementations
  • FIXME for bugs
  • NOTE for simple, but important notes

(5a) Doxygen

  • comment style: ///
  • class docs are placed at the top of the file, surrounded by ///////////////////////// lines
  • simple text formatings are done using html tags

(6) Blank lines

  • use them to separate logical blocks (which should also have an introducing block comment)

(7) Brackets

  • scope brackets {} start on the same line as the corresponding order (separated by a single white space) and end on a separate line
    • exceptions: namespaces, classes, interfaces, methods and structs (where the opening bracket is located on a new line)
  • logical brackets () don't get surrounded by white spaces
  • always use {}, also if they're not neccessary: 
    if(myBool) {
  return S_OK;
}

(8) Pointers

  • int* pMyInt, NOT int *pMyInt
  • int& myInt, NOT int &myInt

(9) Macros, inline methods, register variables, asm etc.

  • use it where speed matters and/or it significantly shortens the code

(10) Friend classes

  • avoid it if possible

(11) Namespaces

  • prefer STL for vectors, lists and similar
  • prefer ATL for strings and COM-related stuff
  • prefer WTL for GUI and things like CPoint
  • ATL is the only global namespace

Templates

class MyClass :
    public MyBaseClass
{
public:
  long tmp;

  void MySub1(void);

protected:
  int MySub2(int i = 20);

private:
  bool flag;
}     // MyClass

for(int i = 0; i < 10; ++i) {
  a[i] = i;
}

if(b) {
  return S_OK;
} else {
  return E_FAIL;
}

if((myInt == 10) && (hr == S_OK)) {
  // do something
}

switch(myLong) {
  case 0:
    DoSomething();
    break;
  case 1:
    DoSomething();
    break;
  default:
    myLong = 10;
    break;
}     // switch(myLong)