annotate HACKING @ 4415:2c3390afe10e

Added a coding guideline document.

Hacking / coding guide for Audacious and Audacious-plugins
==========================================================
(C) Copyright 2008 Audacious Development Team
Written by Matti 'ccr' Hämäläinen <[e-mail]>


Premeable
=========
This document describes the guidelines for people who wish to work on
improving or cleaning up Audacious media player, or any of the plugins
we distribute in the plugins package.

It is probably obvious to anyone who has taken a look into the depths
of Audacious source, that many of these guidelines are not actually
followed currently in all places, if at all.

In fact, the purpose of this document is to act as a target to aim at,
when noticing and cleaning up uncompliant code.. or writing new code.


Coding guidelines
=================

- We use Glib for portability. This means that we have sized integer types
  like gint{16,32,64}, etc. and shorthand types like guint and guchar
  provided, so please do use them.

  Arguably C99 provides inttypes.h with similar types, but C99 support
  may not be complete on all platforms, it is both safer and more uniform
  to use glib types.


- Use other glib functionality, especially string handling like:
  * g_snprintf(), g_strdup_printf(), g_strdup() ...


- However, avoid following Glib things:
  * GString - Useless in most cases compared to normal 'C' string functions
    and introduces conversions back and forth.

  * GList   - GList is slow, either use GQueue or libmowgli lists.


- Be sure to know when you are handling UTF-8 or something else! Glib offers
  special g_ascii_*() functions for certain operations that you might need
  when handling non-unicode strings.


- When reading data from files, it's usually a BIG mistake to read structs
  directly from the stream! This is not portable, as C does not guarantee
  a struct not to have alignment padding (unless the struct is "packed",
  but see below.) In effect sizeof(struct) on some platform may not be
  equal to some other platform.

  Some clever people might think that making struct "packed" via the
  C packed qualifier would be a solution, but this will

  What you SHOULD do is read individual members of the struct one by one
  from the stream. This may sound bothersome, but by doing so, your code
  will be portable.


- Always use Glib sized types for reading integer data from file streams.
  Using plain C types (like 'long int' for example) is not wise, because
  they may be of different size on different platforms depending on the
  platform ABI. For example, on some 64-bit platforms, 'long int' is
  64 bits, while on 32-bit platforms it is 32 bits.


- Audacious core provides some helper functions for reading endian-dependant
  integers from VFS streams (aud_vfs_fget_{le,be}{16,32,64}), see vfs.h and
  documentation for more information.



Additional style guidelines
===========================

- Indentation: Use the same indentation style (also spaces vs. tabs)
  as the file you are editing. In new files/code, use indentation of
  4 spaces (no tabs).

- Whitespace usage in code:

  a = 1;

  if (b == d && !strcmp(a, c)) ...

- Blocks:

  while (...) {
      do_something(...)
  }

  if (...) {
  } else {
  }