manticoresearch/doc/internals-coding-standard.txt

Manticoresearch coding standard
===============================

WARNING. This document is just an internal note. It might or might not be
in sync with the actual code. Use it as an overview; refer to the source
for precise details.

General
--------

This document describes C++ coding standard that MUST be used for
Manticoresearch source code.

It is not yet complete. Currently, we're not aiming for an exhaustive set
of rules (that noone will read anyway). Rather, we're covering only those
gray areas that are not immediately obvious from the source. However,
you should also *first* refer to the source for general look and feel.

Certain rules might change over time. However, the following rules are not
going to be changed:

- All source parts must look alike.
- When in doubt, ask. If not answered, mimic. (And ask again.)

1. General formatting rules
----------------------------

- No duplicate spaces, use tabs.
- Indent is 1 tab.
- Tab size is 4.

2. Formatting C++ clauses
--------------------------

2.1. Enumeration
-----------------

enum Example_e
{
	FIRST		= mandatory_value,
	SECOND,
	THIRD,
	FOURTH
};

Same for typed enums (aka enum class)

enum class TypedExample_e
{
	FIRST,
	SECOND,
	THIRD,
	FOURTH
};

2.2. Switch statement
----------------------

switch ( iMyCondition )
{
	case FIRST:		iShortStatement = 1; break;
	case SECOND:	iAnotherShortStatement = 2; break;
	case THIRD:
		iLongerStatement = 3;
		DoSomething();
		break;
	case FOURTH:
		{
			int iEvenLongerStatementWithLocals = 4;
			DoSomethingElse();
			break;
		}
}

2.3. Parentheses
-----------------

- 1 space around opening '('.
- 1 space before closing ')'.
- Empty argument lists in function calls can omit spaces.
- Short 1-argument lists can omit spaces too.

TypicalCall ( iFirst, sSecond );
NullArglist();
ShortArglist(i);
StillShortArglist(iIdx);
LongEnoughArglist ( iFirst );
iVar = !( iCode & BOOLEAN_EXPRESSION );
if ( i==1 || ( j==2 && k==3 ) ) { ... }
if ( i )  {... }

2.4. Class declaration layout
------------------------------

- Usually, variables go first, then functions.
- Usually, public members go first, then protected, then private.
- All the rules above are not mandatory, but generally suggested.

class SampleClass_c
{
public:
			SampleClass_c ();
			~SampleClass_c ();

	void	DoThings ();

protected:
	int		m_iLocalState;
	bool	m_bSomeFlag;

	int		m_iAnotherLogicalBlock;
	int		m_iOfMemberVariables;

	void	Helper1();
	void	Helper2();
};

3. Naming conventions
----------------------

- Camel case, and reasonable subset of Hungarian notation.
- Identifiers are "MultiWordName", not "multi_word_name" (this is CamelCase).
- "m_" prefix on data members is mandatory (this is Hungarian).
- Single-char typeid prefix on variables is mandatory (this is Hungarian).
	- "i" means int
	- "u" means unsigned
	- "b" means boolean
	- "c" means char
	- "f" means float
	- "h" means hash, i.e. associative array (like std::map)
	- "p" means pointer
	- "pp" means pointer to pointer
	- "s" means string (CSphString)
	- "sz" means char *
	- "e" means enum
	- "d" means array (no idea why "d", maybe "data"?)
	- "t" means any other (complex) type
- Single-char variable names (same as typeid) are allowed for iterator variables
- auto variable names should be prefixed by the typeid of their implied type:
	auto sNewString = sOldString;

- No special rules for public/protected/private member names.

- Enum names must end with "_e":		SomeEnum_e
- Interface names must end with "_i":	SomeInterface_i
- Class names must end with "_c":		SomeClass_c
- Struct names must end with "_t":		SomeStruct_t

class SampleClass_c
{
	int		m_iSomething;	// right, got both "m_" prefix and "i" typeid
	char	iAnotherthing;	// WRONG, bad typeid char, bad capitalization
	long	m_AnotherField;	// WRONG, missing typeid char
	char *	m_lpszWtf;		// WRONG, typeid must be single char (or "pp", "sz")
	...

	/// right
	void SampleCall ( RuleType_e eRule, char cKey, bool bFlag, char * szArg );
};

- constants, either typed or defined, must be all caps:

	const bool FAIL_ON_NULL_SOURCE = false;
	#define READ_NO_SIZE_HINT 0

--eof--