Coding Style Guidelines


This manual contains coding standards and guidelines for 389 Directory Server contributors.

This project has evolved over a very long time (see History). As a result not all of the existing code conforms to these standards. All new code should adhere to these standards but please do not go back and make wholesale formatting changes to the old code. It just confuses things and is generally a waste of time.

Why Have A Coding Style?

For easier maintenance

If you’re merging changes from a patch it’s much easier if everyone is using the same coding style. This isn’t the reality for a lot of our code, but we’re trying to get to the point where most of it uses the same style.

Improved readability

Remember, code isn’t just for compilers, it’s for people, too. If it wasn’t for people, we would all be programming in assembly. Coding style and consistency mean that if you go from one part of the code to another you don’t spend time having to re-adjust from one style to another. Blocks are consistent and readable and the flow of the code is apparent. Coding style adds value for people who have to read your code after you’ve been hit by a bus. Remember that.

General Rules

A better message is:

An error occured processing operation=X: Invalid dn.

A great message is:

ERROR: Processing add operation=X: DN containing "z" is invalid.

Messages should direct a user or admin where to go to solve the problem, not to just make them aware of it.

Statements

Comments

Indentation

Variable Declarations

Types

Configuration

This is a description of how we should create configuration options for our server.

The first example is the best. We have a feature and a clear english “on/off”. We know that feature: on means on, and feature: off means off. The second is the same, but has the word -enable. This is redundant, as the on-off already conveys this. The third will be REJECTED on review, because it’s confusing. feature-disable: on is counter intuitive, meaning it’s disabled. This is hard for a native english speaker, let alone a second language speaker.

In our example we have a cache memory size. This is a good name as we know this is about the cache, memory and size: We can infer that it’s the amount of memory the cache will occupy, and given context by the value as it has a quantifier in it.

The second is bad, because we have no context to what “cache” is related to, be it a size or otherwise. This would require looking documentation.

Remember: DOCUMENTATION exists as an artifact of POOR DESIGN CHOICES. Every piece of documentation represents a possible design flaw in our system.

For a non-native speaker the contraction of memory size to memsz would be confusing.

Command line tools

This describes how we should create command line tools

One of these two is easier to type, and more “natural” to use than the other (hint, it’s the shorter one).

Last modified on 9 March 2017