General

There are some general things to keep in mind independent of the the language you're coding in; specific per-language guidelines can be found in the sub-pages.

Write code to be read by others

Other people (or maybe even you) probably need to read your code one day and have to understand it. Write your code in a way so they can -- adding comments helps there.

Don't use TAB characters

TABs have a high chance of leading to different indenting on other people's editors

Use the style of the rest of the file

Look at the style of the rest of the file you're editing and use that style, even if you don't like it -- this prevents mixing styles, keeping the code clean and looking nice.

Documentation

Good code is documented on multiple levels:

1. As part of the commit that adds it to the code base
2. Mixed with the code to document the intent of the code
3. The API entry points, to document the input parameters, return values and exceptional situations

Commit messages

A good commit message explains why the change is necessary: what is better about the new situation than about the old one. This might include details on which execution environment exhibits the behaviour being changed.

When I am working with peers on writing a commit message, I sometimes use the analogy of a newspaper. Any given newspaper is out of date very quickly. But we keep newspaper archives and store copies of every single newspaper.
Why? Because we don't know when we will need to refer to them, or which ones we will refer to. All that we know is that some of them will vital in future, as the journal of record.

The first line summarizes the change, further lines provide details to the author's thinking (e.g. the commit message for 45dac95):

* Change comparison periods selector to a number spinner

Note that the UI for the period selector was apparently not intuitive
enough as the recent UI change was not understood by existing users.
By changing the NumberTextBox to a NumberSpinner, pre-filled with zero
the user should feel invited to change the number input.

API documentation

LedgerSMB provides multiple APIs:

• PL/pgSQL
• Perl
• Web service

Each element published through one of these APIs must be documented in a way that allows the reader of the documentation to use the API without reading the code behind it. For Perl code, documentation must be written in POD, for SQL code, the documentation must be written in COMMENT ON statements. Both are input for documentation generators to generate browsable documentation.

By "documented in a way that allows the reader of the documentation to use the API without reading the code", we mean that the code should document:

• The inputs expected
• The returned value(s) and their types under all applicable conditions
• Potential side effects of running the function

The coding structure of a module should follow (and be in-lined in) the POD itself.  This ensures that the documentation of the interface and the function are next to eachother.

Methods which are not part of the API have to be documented just as the public ones. In contrast, they are documented with inline comments instead of POD. The content of the inline comment has the same structure as though they were POD. This difference in documentation type prevents the documentation of the private functions to be "leaked" into the public documentation.

Inline code comments

As Chris puts it in an e-mail to the developers list: "comments should describe things which are outside the code -- why's and wherefore's, promises to developers, reasoning, etc.  

# we need to ___ because ___

is a good comment. Bad ones are e.g.:

# let's ___

and

# set the gl_description

Concluding: Inline comments should be reserved for cases where the comments are needed to explain coding decisions: comments should explain why, not how.