HACKING.txt

Hacking ccache
==============

Code formatting
---------------

* Use tabs for indenting and spaces for aligning C code.
* Use 4 spaces for indenting other code (and spaces for aligning).
* Put the opening curly brace on a new line when defining a function, otherwise
  at the end of the same line.
* Put no space between function name and the following parenthesis.
* Put one space between if/switch/for/while/do and opening curly brace.
* Always use curly braces around if/for/while/do bodies, even if they only
  contain one statement.
* If possible, keep lines at most 80 character wide for a 2 character tab
  width.
* Use only lowercase names for functions and variables.
* Use only uppercase names for enum items and (with some exceptions) macros.
* Don't use typedefs for structs and enums.
* Use //-style comments.

Tip: Install the tool uncrustify <http://uncrustify.sourceforge.net> and then
run "make uncrustify" to fix up source code formatting.

Idioms
------

* Declare variables as late as convenient, not necessarily at the beginning of
  the scope.
* Use NULL to initialize null pointers.
* Don't use NULL when comparing pointers.
* Use format(), x_malloc() and friends instead of checking for memory
  allocation failure explicitly.
* Use str_eq() instead of strcmp() when testing for string (in)equality.
* Consider using str_startswith() instead of strncmp().
* Use bool, true and false for boolean values.
* Use tmp_unlink() or x_unlink() instead of unlink().
* Use x_rename() instead of rename().

Other
-----

* Strive to minimize use of global variables.
* Write test cases for new code.

Commit messages
---------------

* Write a summary (short description) on the first line.
* Start the summary with a capital letter. Optional: prefix the short
  description with a context followed by a colon.
* The summary should be in imperative mood (see examples below).
* The summary should not end with a period. It's a title and titles don't end
  with a period.
* If a longer description is wanted, add a second line empty and write the
  longer description on line three and below.
* Keep lines in the message at most 72 characters wide.

Example 1:

    Hash a delimiter string between parts to separate them

    Previously, "gcc -I-O2 -c file.c" and "gcc -I -O2 -c file.c" would hash
    to the same sum.

Example 2:

    win32: Add a space between filename and error string in x_fmmap()

See also:

* http://stopwritingramblingcommitmessages.com
* http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
* https://github.com/erlang/otp/wiki/Writing-good-commit-messages