This file is inspired by Jasper's HACKING file for xfce4-panel, and gives a
decent idea of the coding style I prefer for xfdesktop, as well as random
hacking guidelines.  If you submit a patch, please be sure to conform to 
these 'rules'.  If anything isn't clear, just ask (private mail is fine).
     -brian (bjt23@cornell.edu)

last modified: 2006/12/30

* Coding style:
  - Line length: I try to keep to a rough 80 characters, as I do sometimes
    edit code in a terminal.  If it gets a little longer, that's fine, but
    excessively long lines (>100 chars) should be broken up.  Break up
    function calls on parameter boundaries if possible, by lining up the
    parameters on the next line with the first parameter on the previous
    line.
  - Braces: on the same line as the if/while/etc. statement.  Braces should
    be omitted for one-line blocks.  As an exception, the opening brace after
    a function declaration goes on its own line.
  - Parentheses: Never put a space before the opening parentheses for
    if/while/etc. statements or function calls.  No space on the inside of the
    parentheses either.  No space between the closing parenthesis of a
    type cast and the variable name.
  - Function declarations: return type goes on the first line, function name
    and first parameter on the second line.  Second and further parameters
    each get their own line, and they should be aligned with the start of
    the first parameter.  Please do not add spaces between the type and
    variable name to line up the variable names.  As specified before, the
    opening brace also gets its own line.
  - Indentation: four spaces.  No tab characters.
  - Variable declarations: don't line up the variable names by padding shorter
    type names with spaces.  Feel free to combine multiple same-type
    declarations to the same line.

NB: Some parts of the code don't conform to the above style.  That just means
that it's *really* old code that existed before I took over as maintainer,
or it's stuff that I wrote using a slightly different style (I do change my
mind sometimes).  When in doubt, follow the style outlined above.

* Other stuff:
  - Regardless of what gcc supports, all variable declarations should appear
    at the top of the function, without any normal statements in between
    (though it's ok to initialise variables where they're declared).
  - I generally try to declare variables in the rough order they'll be used
    in the function.  This makes it easier if I have to go back later and
    figure out what's going on and what's getting used where.
  - I won't check in code that doesn't compile when you pass
    --enable-debug=full to configure.  This means it must not cause compiler
    warnings.
  - Comments are useful to explain stuff that's complicated or to enumerate
    why the various branches of an 'if' tree are being taken if the logic
    is somewhat complex.  Otherwise I tend not to comment my code all that
    much (not saying this is good or bad; just fact).
  - ChangeLog: don't bother modifying the toplevel ChangeLog.  It gets
    automatically generated using the 'svn2cl' script before releases.
  - Other committers with access to the xfdesktop tree should feel free to
    make small commits related to minor one-line bugfixes and fixes for
    compiler warnings.  The release manager may make whatever changes needed
    during the release process to make xfdesktop release-ready.  I do
    appreciate a quick note via email if you make any changes, though I'll
    probably notice it via the xfce4-commits mailing list.  The po/ and
    po-doc/ directories are under control of the xfce-i18n team.
    
* Code sample:

static void
example_foo_function(FooObject *cheese,
                     gboolean bar,
                     gint baz)
{
    gint i, j;
    BarObject *monkey = BAR_OBJECT(monkey);
    const gchar *happy_string;
    
    if(bar)
        do_something();
    else {
        really_long_function_call(cheese, "I like to eat cheese all the time",
                                  baz, monkey);
        do_something_else();
    }
    
    /* ... */
}

* Code layout:
  - /common/
    + Stuff that's used in multiple places.
  - /settings/
    + This implements xfdesktop-settings a stand-alone program as well as a
      plugin for the xfce4-settings-manager.
  - /src/main.c
    + This basically just the main function, it then calls the xfdesktop-application.
  - /src/xfdesktop-application.c Handles the startup and shutdown of xfdesktop.
      It uses GApplication to handle message passing, process uniqueness,
      parses the command line, and other related tasks.
  - /src/menu.c
    + This actually contains very little menu code.  It just accepts the mouse
      button press and pops up the menu, along with some other random stuff.
  - /src/windowlist.c
    + This guy assembles a list of open windows on each workspace and
      constructs a nifty menu to display them all.
  - /src/xfce-backdrop.c
    + This (XfceBackdrop) represents a backdrop image.  It handles scaling and
      compositing as well and has code to handle rotating the backdrop image.
  - /src/xfce-desktop.c
    + This is a GtkWindow subclass which is the actual desktop window.
      xfdesktop displays one XfceDesktop window for each X screen, and may
      have several XfceWorkspace objects associated with it based on the
      number of workspaces configured.
  - /src/xfce-workspace.c
    + This represents a workspace on the system and contains a list of
      XfceBackdrops used to represent that workspace, usually one per
      monitor. It also sets the properties of the XfceBackdrop and handles
      the migration from the pre4.11 xfconf settings to the modern ones.
  - /src/xfdesktop-icon-view.c
    + XfdesktopIconView is a relatively simple (at least it started out that
      way) icon view widget for the desktop.  It only supports a fixed grid
      of icons, which can be rearranged via drag-and-drop.  It does not
      support arbitrary positioning.  The grid resizes automatically if the
      screen size changes or if the icon/font size changes.  There are a
      bunch of annoying things in here to support arbitrary desktop icon
      types.  You should *never* assume that the user is viewing normal file
      icons here.  So the icon view can't know about files, or about dropping
      things onto icons, or what happens when a DnD event occurs from
      another application, etc.  The icon view doesn't even know where the
      icons come from or what they represent.
  - /src/xfdesktop-icon.c
    + XfdesktopIcon is an abstract icon object.  You can add them to or
      remove them from an XfdesktopIconView.  You can set their positions,
      and figure out the icon's rectangular bounding box after it's been
      placed in the icon view.  The icon also reports what kinds of drag
      and drop actions it supports, and if it can display a tooltip.  It
      can also have its own special popup menu.
  - /src/xfdesktop-icon-view-manager.c
    + XfdesktopIconViewManager is an abstract controller for the icon view.
      It's responsible for creating the XfdesktopIcon objects and adding them
      to the XfdesktopIconView.  It handles drag and drop events for certain
      situations (like dropping data from another app onto an empty area of
      the desktop).  Most of the heavy lifting should go here.

TODO: document the actual window icon and file icon implementations.