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 bugzilla.gnome.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 Anything in Util that requires gtk+ or gnome should be added to the UiUtil.dll
  35 assembly.  Otherwise, add it to the Util.dll assembly.
  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 unnecessary 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                 * However, when defining loops where the subpart could be
 129                   considered one statement, use open/close braces for
 130                   clarity.  For example:
 131
 132                         good:
 133                                 while (true) {
 134                                         if (a)
 135                                                 foo = true;
 136                                 }
 137
 138                         bad:
 139                                 while (true)
 140                                         if (a)
 141                                                 foo = true;
 142
 143
 144                 * When defining a method, use the C style for brace placement,
 145                   that means, use a new line for the brace, like this:
 146
 147                         good:
 148                                 void Method ()
 149                                 {
 150                                 }
 151
 152                         bad:
 153                                 void Method () {
 154                                 }
 155
 156                 * Properties and indexers are an exception, keep the
 157                   brace on the same line as the property declaration.
 158                   Rationale: this makes it visually
 159                   simple to distinguish them.
 160
 161                         good:
 162                                 int Property {
 163                                         get {
 164                                                 return value;
 165                                         }
 166                                 }
 167
 168                         bad:
 169                                 int Property
 170                                 {
 171                                         get {
 172                                                 return value;
 173                                         }
 174                                 }
 175
 176                   Notice how the accessor "get" also keeps its brace on the same
 177                   line.
 178
 179                   For very small properties, you can compress things:
 180
 181                         ok:
 182                                 int Property {
 183                                         get { return value; }
 184                                         set { x = value; }
 185                                 }
 186
 187                 * Use white space in expressions liberally, except in the presence
 188                   of parenthesis:
 189
 190                         good:
 191
 192                                 if (a + 5 > Method (Blah () + 4))
 193
 194                         bad:
 195                                 if (a+5>Method(Blah()+4))
 196
 197                 * This also applies for "for" loops:
 198
 199                         good:
 200                                 for (int i = 0; i < 100; i++)
 201
 202                         bad:
 203                                 for (int i=0;i<100;i++)
 204
 205                 * For any new files, please use a descriptive introduction, like
 206                   this:
 207
 208                         //
 209                         // System.Comment.cs: Handles comments in System files.
 210                         //
 211                         // Copyright (C) 2002 Address, Inc. (http://www.address.com)
 212                         //
 213
 214                 * Switch statements have the case at the same indentation as the
 215                   switch:
 216
 217                         switch (x) {
 218                         case 'a':
 219                                 ...
 220                         case 'b':
 221                                 ...
 222                         }
 223
 224                 * Large switch statements should have blank lines
 225                   between case statements:
 226
 227                          switch (x) {
 228
 229                          case 'a':
 230                                 large code chunk;
 231
 232                          case 'b':
 233                                 another code chunk;
 234
 235                          default:
 236                                 another code chunk;
 237                          }
 238
 239                 * All method names and properties should be StudlyCapped.
 240
 241                 * Private variable members of a class and function
 242                   local variable names should be under_scored (no
 243                   camelCase please).
 244
 245 If you are using Emacs, you might want to put something like this
 246 in your .emacs file:
 247
 248 (defun poor-mans-csharp-mode ()
 249   (java-mode)
 250   (setq mode-name "C#")
 251   (set-variable 'tab-width 8)
 252   (set-variable 'indent-tabs-mode t)
 253   (set-variable 'c-basic-offset 8)
 254   (c-set-offset 'inline-open 0)
 255   (c-set-offset 'case-label 0)
 256 )
 257
 258 (setq auto-mode-alist (append '(("\\.cs\\'" . poor-mans-csharp-mode))
 259                               auto-mode-alist))
 260