HACKING

   1
   2 CVS
   3 ---
   4
   5 Beagle's source repository is in GNOME CVS, in the module 'beagle'.
   6
   7 For information on GNOME CVS, see:
   8 http://developer.gnome.org/tools/cvs/html.
   9
  10
  11 Patches
  12 -------
  13
  14 If you have a patch you'd like to submit, please open a tracking bug on
  15 gnome.bugzilla.org (product 'beagle').  Attach the patch (and any additional
  16 required files) to the bug.  The core developers are all on the beagle-bugs
  17 mailing list, so we'll see that it is there.  We will review it, but if people
  18 are busy it might not happen right away.
  19
  20 In the past we'd been doing patch review on the mailing list, but that hasn't
  21 always worked very well.  Sometimes patches get lost in the shuffle.
  22
  23
  24 Organization
  25 ------------
  26
  27 Code that parses files or otherwise interacts w/ low-level details from
  28 third-party apps (i.e. parsing gaim logs, undocumented nautilus metafiles and
  29 stuff from .gnome2/epiphany, etc.) should probably be broken out into small
  30 chunks of semi-independent code and placed in Beagle/Util.  That kind of code
  31 is just ugly by nature, and I want to keep it from getting mixed into the
  32 beagle code as much as possible.
  33
  34 We also want to avoid non-core dependencies in Util.  Anything in Util that
  35 requires gtk+ or gnome should go into a separate UtilUi at some point.
  36
  37
  38 Coding Style
  39 ------------
  40
  41 Beagle attempts to follow the Mono coding conventions.  The following
  42 description of those conventions was shamelessly stolen from Dashboard's
  43 HACKING file.
  44
  45 * Tagging buggy code
  46
  47         If there is a bug in your implementation tag the problem by using
  48         the word "FIXME" in the code, together with a description of the
  49         problem.
  50
  51         Do not use XXX or TODo or obscure descriptions, because
  52         otherwise people will not be able to understand what you mean.
  53
  54
  55 * Basic code formatting
  56
  57         In order to keep the code consistent, please use the following
  58         conventions.  From here on `good' and `bad' are used to attribute
  59         things that would make the coding style match, or not match.  It is not
  60         a judgement call on your coding abilities, but more of a style and
  61         look call.  Please follow these guidelines to ensure prettiness.
  62
  63         Use 8 space tabs for writing your code.
  64
  65         Since we are using 8-space tabs, you might want to consider the Linus
  66         Torvalds trick to reduce code nesting.  Many times in a loop, you will
  67         find yourself doing a test, and if the test is true, you will
  68         nest.  Many times this can be changed.  Example:
  69
  70
  71                 for (i = 0; i < 10; i++) {
  72                         if (Something (i)) {
  73                                 DoMore ();
  74                         }
  75                 }
  76
  77         This take precious space, instead write it like this:
  78
  79                 for (i = 0; i < 10; i++) {
  80                         if (! Something (i))
  81                                 continue;
  82                         DoMore ();
  83                 }
  84
  85         A few guidelines:
  86
  87                 * Use a space before an opening parenthesis when calling
  88                   functions, or indexing, like this:
  89
  90                         Method (a);
  91                         b [10];
  92
  93                 * Do not put a space after the opening parenthesis and the
  94                   closing one, ie:
  95
  96                         good: Method (a);       array [10];
  97
  98                         bad:  Method ( a );     array[ 10 ];
  99
 100                 * Inside a code block, put the opening brace on the same line
 101                   as the statement:
 102
 103                         good:
 104                                 if (a) {
 105                                         Code ();
 106                                         Code ();
 107                                 }
 108
 109                         bad:
 110                                 if (a)
 111                                 {
 112                                         Code ();
 113                                         Code ();
 114                                 }
 115
 116                 * Avoid using unecessary open/close braces, vertical space
 117                   is usually limited:
 118
 119                         good:
 120                                 if (a)
 121                                         Code ();
 122
 123                         bad:
 124                                 if (a) {
 125                                         Code ();
 126                                 }
 127
 128                 * When defining a method, use the C style for brace placement,
 129                   that means, use a new line for the brace, like this:
 130
 131                         good:
 132                                 void Method ()
 133                                 {
 134                                 }
 135
 136                         bad:
 137                                 void Method () {
 138                                 }
 139
 140                 * Properties and indexers are an exception, keep the
 141                   brace on the same line as the property declaration.
 142                   Rationale: this makes it visually
 143                   simple to distinguish them.
 144
 145                         good:
 146                                 int Property {
 147                                         get {
 148                                                 return value;
 149                                         }
 150                                 }
 151
 152                         bad:
 153                                 int Property
 154                                 {
 155                                         get {
 156                                                 return value;
 157                                         }
 158                                 }
 159
 160                   Notice how the accessor "get" also keeps its brace on the same
 161                   line.
 162
 163                   For very small properties, you can compress things:
 164
 165                         ok:
 166                                 int Property {
 167                                         get { return value; }
 168                                         set { x = value; }
 169                                 }
 170
 171                 * Use white space in expressions liberally, except in the presence
 172                   of parenthesis:
 173
 174                         good:
 175
 176                                 if (a + 5 > Method (Blah () + 4))
 177
 178                         bad:
 179                                 if (a+5>Method(Blah()+4))
 180
 181                 * For any new files, please use a descriptive introduction, like
 182                   this:
 183
 184                         //
 185                         // System.Comment.cs: Handles comments in System files.
 186                         //
 187                         // Author:
 188                         //   Juan Perez (juan@address.com)
 189                         //
 190                         // (C) 2002 Address, Inc (http://www.address.com)
 191                         //
 192
 193                 * Switch statements have the case at the same indentation as the
 194                   switch:
 195
 196                         switch (x) {
 197                         case 'a':
 198                                 ...
 199                         case 'b':
 200                                 ...
 201                         }
 202
 203
 204 If you are using Emacs, you might want to put something like this
 205 in your .emacs file:
 206
 207 (defun poor-mans-csharp-mode ()
 208   (java-mode)
 209   (setq mode-name "C#")
 210   (set-variable 'tab-width 8)
 211   (set-variable 'indent-tabs-mode t)
 212   (set-variable 'c-basic-offset 8)
 213   (c-set-offset 'inline-open 0)
 214   (c-set-offset 'case-label 0)
 215 )
 216
 217 (setq auto-mode-alist (append '(("\\.cs\\'" . poor-mans-csharp-mode))
 218                               auto-mode-alist))
 219