Haiku OS Development

https://www.haiku-os.org/development
Admin
This documentation provides a comprehensive guide for developers on how to contribute to the Haiku...
Tokens:13,165
Snippets:147
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Pointer Initialization Style

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the preferred method for initializing pointers to `NULL`. It advocates for direct assignment (`BView* view = NULL;`) over constructor call syntax (`BView* view(NULL);`), which is considered less traditional for pointer initialization.

```cpp
// wrong
BView* view(NULL);

// Correct assignment style
BView* view = NULL;
```

--------------------------------

### Include Statement Order and Grouping

Source: https://www.haiku-os.org/development/coding-guidelines

Provides guidelines for organizing `#include` statements, prioritizing the header belonging to the source file first, followed by standard library headers, Haiku API headers, and then local headers. This convention improves self-containment and dependency clarity.

```cpp
/*
 * Copyright 2004-2007, Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 * 		Jonathan Smith, optional@email
 * 		Developer Name, optional@email
 */


#include "ThisClass.h"

// POSIX API headers
#include <stdio.h>
#include <string.h>

// Haiku API headers
#include <file.h>
#include <os.h>

#include <privateheader.h>

#include "OtherLocalHeaders.h"


void
ThisClass::SomeMethod()
{
  // ...
}


int32
ThisClass::SomeOtherMethod()
{
  // ...
}

// ...
```

--------------------------------

### Haiku Header File Copyright and Structure

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the structure for header files in Haiku OS, including the copyright notice, header guard, and spacing requirements. It shows the placement of includes and class definitions relative to the header guard.

```c++
/*
 * Copyright 2004-2007, Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Jonathan Smith, optional@email
 *		Developer Name, optional@email
 */
#ifndef THIS_CLASS_H
#define THIS_CLASS_H


#include <Message.h>


class ThisClass {
// ...
};


#endif // THIS_CLASS_H
```

--------------------------------

### C++ Class and Function Formatting for Haiku OS

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates C++ class definitions, constructors, destructors, member functions, and static methods according to Haiku OS formatting standards. This includes indentation rules, placement of access specifiers, and handling of long argument lists.

```cpp
class Foo : public Bar {
public:
								Foo(int32);
	virtual						~Foo();

	virtual void						SomeFunction(SomeType* argument);

	// indent long argument lists by a tab:
	virtual const char*		 FunctionLotsOfArguments(const char* name,
																										const char* path, const char* user);

private:
				int32				   _PrivateMethod();
	static  int32				   _SomeStaticPrivateMethod();

// Redundant private: to separate the fields from the methods:
private:
	volatile int32				 fMember;
		const char*				 fPointerMember;
};


// The ':' always comes on its own line, initializers following
Foo::Foo(int32 param)
	:
	Bar(int32* param),
	fMember(param),
	fPointerMember(NULL)
{
	...
}


/*! Function descriptions are using doxygen style. Please note, this is not
	 a place for end-user documentation, but for documentation that helps
	 understanding the code, and using the functions correctly.
*/
template const T*
Foo::Bar(const char* bar1, T bar2)
{
	...
}


// Empty functions in class definitions can be written on a single line
class Example {
public:
		void			FooFunction() {}
};


// Empty functions defined outside a class must be formatted the same as other functions
void
Foo::FooFunction()
{
}

```

--------------------------------

### Haiku Source File Copyright and License Notice (MIT License)

Source: https://www.haiku-os.org/development/coding-guidelines

This is the preferred format for source file copyright and license notices in Haiku OS development, adhering to the MIT License. It includes copyright years, Haiku, Inc., and listed authors with optional email addresses.

```c++
/*
 * Copyright 2004-2007, Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Jonathan Smith, optional@email
 *		Developer Name, optional@email
 */
```

--------------------------------

### Haiku OS Constant Declaration

Source: https://www.haiku-os.org/development/coding-guidelines

Illustrates the convention for declaring constants in Haiku OS, which is to prefix them with 'k'. This naming convention aids in identifying constants within the codebase.

```cpp
const uint32 kOpenFile = 'open';

```

--------------------------------

### C++ Conditional and Loop Formatting for Haiku OS

Source: https://www.haiku-os.org/development/coding-guidelines

Shows idiomatic C++ formatting for if-else statements, complex conditions, and loops (for loops) as per Haiku OS guidelines. Emphasizes correct indentation for nested conditions and long lines.

```cpp
if (someCondition) {
	DoSomething();
		// Comments that only affect a single line are usually
		// written after it, and are indented by a single tab
	DoSomethingElse();
} else if (someOtherCondition) {
	DoSomethingElse();
	DoSomething();
}

if (someVeryVeryLongConditionThatBarelyFitsOnALine
	&& someOtherCondition) {
	// && operator on the beginning of the next line,
	// indented by a tab
	...
}

if (someVeryVeryLongConditionThatBarelyFitsOnALine
	&& (someVeryLongNestedConditionPart1
		|| someVeryLongNestedConditionPart2)
	&& lastPartOfSomeVeryVeryLongCondition
		!= 0) {
	// Indent one tab per expression level
	...
}

if (fMemberPointer->VeryLongFunctionCall(uint32 argument1,
		uint32 argument2, uint32 argument3) != NULL
	&& someOtherCondition) {
	// Function call parenthesis count as an expression
	// level thus the additional tab on the second line.
	...

	localVariable = AnotherLongFunction(uint32 argument1,
		uint32 argument2, uint32 argument3);
		// For this simple assignment though
		// an additional tab wouldn't help readability.

	anotherVariable = fSomeUselessRGBColor.alpha
		* (fSomeUselessRGBColor.red + fSomeUselessRGBColor.green
			+ fSomeUselessRGBColor.green + fOffset.blue)
		/ 3 + fBrightness;
		// This one spans more than two lines, we add
		// a tab to distinguish the expression level
		// in parenthesis.
}

for (int32 index = 0; index < count; index++) {
	DoSomething(index);
	DoSomethingElse(index);
}

// Omit braces for single line statements, place statement on a new line
// (but always use braces around multi-line statements)

if (condition)
	DoOneThingOnly(index);

for (int32 index = 0; index < count; index++)
	DoOneThingOnly(index);

// switch statement formatting

switch (condition) {
	case label1:
		DoSomething();
		break;

	case label2:
	{
		// need extra curly brackets here because of count
		// declaration
		int32 count;
		...
		DoSomething();
		break;
	}
}

...
	CallingSomeFunction(firstArgument * 2 + someMoreStuff,
		secondArgument, thirdArgument);
		// Indent long argument lists by a tab
...

	const rgb_color kNeonBlue = {10, 10, 50, 255};

```

--------------------------------

### Boolean Conditions vs. Pointer/Integer Logic

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the preferred method of using explicit boolean conditions (e.g., `pointer != NULL`, `intValue != 0`) in conditional statements over relying on implicit boolean conversions of pointers or integers. This approach enhances code readability and reduces potential ambiguity.

```cpp
// This is how it should look like:
if (pointer != NULL || anotherPointer == NULL || intValue != 0)
    ...

int32 value;
bool doThings = (value != 0);

// wrong - don't use the following style
if (pointer || !anotherPointer || intValue)
    ...

int32 value;
bool doThings = value;
```

--------------------------------

### C++ Static Function Definition for Haiku OS

Source: https://www.haiku-os.org/development/coding-guidelines

Illustrates the formatting for a static function definition in C++, adhering to Haiku OS coding standards. This includes the return type, function name, parameter list, and function body indentation.

```cpp
static int32
my_static_function()
{
	return 42;
}

```

--------------------------------

### Haiku OS Commenting Style: Explaining 'Hacks'

Source: https://www.haiku-os.org/development/coding-guidelines

Shows the preferred method for commenting on potentially problematic code sections ('hacks') in Haiku OS. Instead of simply marking it as a 'hack', the comment should explain the underlying reason, such as fragility or lack of overflow handling.

```cpp
// the following code is fragile because it doesn't
// handle overflows properly

```

--------------------------------

### Haiku OS Member Variable Declaration

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the convention for declaring member variables in Haiku OS, which is to prefix them with 'f'. This helps distinguish member variables from local variables and other types.

```cpp
int32 fMemberVariable;

```

--------------------------------

### Haiku OS Commenting Style: Line Comment

Source: https://www.haiku-os.org/development/coding-guidelines

Illustrates the preferred style for line comments in Haiku OS, where comments are placed on a new line and indented with a tab to explain a specific line of code. This ensures comments do not clutter the main code flow.

```cpp
...
BPoseView::WatchNewNode(&itemNode, watchMask, lock.Target());
		// have to node monitor ahead of time because
		// Model will cache up the file type and preferred
		// app (comment about the above line)

```

--------------------------------

### Alternative Copyright Notice for Individual Contributions

Source: https://www.haiku-os.org/development/coding-guidelines

An alternative format for copyright headers when an individual prefers to keep the copyright to themselves, allowing for multiple authors and specific copyright years. It also specifies the MIT License.

```c++
/*
 * Copyright 2007 Jane Doe, optional@email
 * Copyright 2003-2005 Some Developer, optional@email
 * All rights reserved. Distributed under the terms of the MIT License.
 */
```

--------------------------------

### Code Structure After Copyright Header in Haiku Files

Source: https://www.haiku-os.org/development/coding-guidelines

Illustrates the required spacing after the copyright header and before the main content of a file in Haiku OS development. This includes two blank lines separating the header from the include directives and subsequent code.

```c++
/*
 * Copyright 2004-2007, Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Jonathan Smith, optional@email
 *		Developer Name, optional@email
 */


#include "ThisClass.h"
// ...
```

--------------------------------

### Haiku OS Commenting Style: Block Comment

Source: https://www.haiku-os.org/development/coding-guidelines

Shows the preferred style for block comments in Haiku OS, where comments are placed above a chunk of code to explain its purpose. This improves readability for larger code sections.

```cpp
// the trash window needs to display a union of all the
// trash folders from all the mounted volumes
// (comment about a block of code)
BVolumeRoster volumeRoster;
volumeRoster.Rewind();
BVolume volume;
while (volumeRoster.GetNextVolume(&volume) == B_OK) {
	if (!volume.IsPersistent())
		continue;
	...
}

```

--------------------------------

### Comparison with Constants Style

Source: https://www.haiku-os.org/development/coding-guidelines

Discourages placing constants on the left side of comparison operators (e.g., `B_OK == file.InitCheck()`). The recommended practice is to place the variable or function call on the left, which aligns with common coding styles and allows compiler warnings to catch accidental assignments.

```cpp
// don't use this style
if (B_OK == file.InitCheck())
    ...

// Preferred style
if (file.InitCheck() == B_OK)
    ...
```

--------------------------------

### Haiku OS Commenting Style: Avoiding Long Inline Comments

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the recommended practice of avoiding long comments on the same line as code in Haiku OS. Instead, comments should be placed on separate lines for better readability.

```cpp
...
if (this < is && a < very && long != condition) {
		// this comment is about the long condition
		// above and is much easier to read!
	...
}

```

--------------------------------

### Avoiding `else` after `return` in `if`-blocks

Source: https://www.haiku-os.org/development/coding-guidelines

Explains that when a `return` statement is used within an `if`-block, a subsequent `else` is unnecessary and reduces code clarity. This pattern simplifies control flow by eliminating redundant branching.

```cpp
// This is how it should look like -- notice, no 'else':
if (something) {
    ...
    return true;
}
if (somethingElse) {
    ...
    return true;
}
return false;

// Wrong - don't use code like below:
if (something) {
    ...
    return true;
} else if (somethingElse) {
    ...
    return true;
} else
    return false;
```

--------------------------------

### Avoiding Assignments in Conditional Statements

Source: https://www.haiku-os.org/development/coding-guidelines

Illustrates incorrect and correct ways to handle assignments within conditional statements like `if` and `while`. The preferred method avoids direct assignment in the condition, promoting clearer and less error-prone code by separating the assignment from the check.

```cpp
// wrong
if ((err = entry.GetRef(&ref)) == B_OK)
    ...

// wrong
BMenuItem* item;
int32 index = 0;
while ((item = ItemAt(index++)) != NULL) {
    ...
}

// Correct 'for' loop alternative
for (int32 index = 0; ; index++) {
    BMenuItem* item = ItemAt(index);
    if (item == NULL)
        break;
    ...
}
```

--------------------------------

### C++ Casting vs C Casting

Source: https://www.haiku-os.org/development/coding-guidelines

Demonstrates the preferred use of C++ style casts (dynamic_cast, static_cast, const_cast, reinterpret_cast) over traditional C-style casts for improved type safety and clarity in C++ code. C++ casts are generally safer as they perform more checks at compile time or runtime.

```cpp
// C++ style cast is preferred
WirelessNetworkMenuItem* wirelessItem = dynamic_cast<WirelessNetworkMenuItem*>(menuItem);
// example C-style cast, note that there is _no_ whitespace after the cast operator
int count = avcodec_count_frames((const uint8_t *)buffer, bufferSize);
```

--------------------------------

### Safe Pointer Deletion

Source: https://www.haiku-os.org/development/coding-guidelines

Shows the incorrect practice of checking for NULL before `delete` or `free` on pointers. C++'s `delete` and C's `free` are designed to handle NULL pointers safely, so explicit checks are redundant and unnecessary.

```cpp
// wrong
if (fIcon != NULL)
    delete fIcon;

// wrong
if (fIconBuffer != NULL)
    free(fIconBuffer);
```

--------------------------------

### Parentheses in Conditional Bitmask Checks

Source: https://www.haiku-os.org/development/coding-guidelines

Highlights the importance of using parentheses correctly when checking bitmasks in conditional statements. Proper use of parentheses ensures correct operator precedence, preventing logical errors that can arise from C/C++'s default operator evaluation order.

```cpp
// Correct usage with parentheses for bitmask checks
if ((a & 3) != 0 && (b & 4) == 0)
    ...

// wrong - C/C++ operator precedence works differently
if (a & 3 && xyz)
    ...
```
Tokens:
Raw