Support This Project

Coding Style (DRAFT ONLY)

Draft

This is a draft document that is work in progress. Please feel free to discuss and modify this document to help improve the wzdftpd coding style standard. You do not have to adhere to any of the rules listed within this document until a final standard has been agreed upon.

Introduction

wzdftpd has a set of code style standards which must be followed when writing code for the project. Some of the reasons for having standard code style throughout the wzdftpd project are listed:

  • provides code consistency throughout the project
  • increases readability of the code, leading to:
    • faster and easier development
    • reduced chance of malicious code being missed by code reviewers
  • ensures that all developers can better communicate with each other
  • makes it easier for outsiders to start developing wzdftpd
  • allows developers to easily configure their editors to show wzdftpd code in a way that suits them best

Note that you can still use your own preferred code styling method in your local development environment. However if you wish to submit patches, you should convert those patches into the format required by the wzdftpd project. Failure to do so may result in your patches taking longer to get submitted to the repository (as it is more work for other developers, who have better things to do). You may be able to use automatic code styling software such as Artistic Style to help automate the task of converting code between the wzdftpd code style, and your own preferred style.

Indentation

Tab characters for indentation

Rule: You must only use a single tab character for each increase in indentation.

Rationale:

  • Using a single tab character for each indentation level allows users to define their own personal indentation width.

Suggested tab character width

Suggestion: It is suggested that you set your editor to treat a tab character as having the same width as 8 characters.

Rationale:

  • This standard is used by the Linux Kernel Project and many other large and popular development communities.
  • A large indentation width helps with code readability, especially after many long hours staring at code.

Wrapping long lines

Rule: Do not extend long lines of code across multiple lines.

Rationale:

  • Long lines of code often indicate that you're doing something wrong, such as:
    • Nesting your code too deep within if, for, do and switch statements.
    • Writing functions that are too complicated. Split long functions if at all possible.
  • Developers should be able to edit the code on screens which are a width of their choosing.
  • Most text editors have plenty of customizable options to allow individual developers to wrap code to their own preference.
  • Wrapping long lines of code hides the complexity of that code from a developer quickly scanning the code for areas that need improvement.

This is bad: 

struct something *pointer_to_the_struct = convert_something_to_something_else(
	(struct something2 *)the_first_argument, (int)the_second_argument,
	the_third_argument);

This is better: 

struct something *obj;
struct something2 *arg1;
int arg2;

arg1 = (struct something2 *)first_argument;
arg2 = (int)second_argument;
obj = something_to_something2(arg1, arg2, third_argument);

Statements and assignments

Multiple statements and assignments on the same line

Rule: Do not place more than one statement or assignment on the same line.

Rationale:

  • Placing multiple statements on the same line hides important code in long lines of text and can make it easier to hide malicious code.
  • Patching and tracking code changes is made a lot harder when multiple statements and assignments are bundled together on the same line.

This is bad: 

int something, something2; do_something(); do_something_else();

This is good: 

int something;
int something2;

do_something();
do_something_else();

Location of pointers

Rule: Pointers should always be placed directly before the function name or variable name.

Rationale: Multiple assignments are not allowed to be placed on the same line, but if they were, consider the following declaration of variables: 

int *var1, *var2;

The pointer character needs to be placed directly before the variable name rather than directly after the type name. Otherwise you'd be declaring one pointer to an integer (var1) and one integer (var2).

This is bad: 

char * something;

some_function(char** arg1, char * arg2);

This is good: 

char *something;

some_function(char **arg1, char *arg2);

To be continued…