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                 * Please also use spaces and clear language (capitalization,
 206                   punctuation) in comments:
 207
 208                         good:
 209                                 // It's going to crash if we're not careful.
 210
 211                         bad:
 212                                 //its going to crash if were not careful
 213
 214                 * For any new files, please use a descriptive introduction, like
 215                   this:
 216
 217                         //
 218                         // System.Comment.cs: Handles comments in System files.
 219                         //
 220                         // Copyright (C) 2002 Address, Inc. (http://www.address.com)
 221                         //
 222
 223                 * Also remember to include the license in comments at the top of
 224                   the file.  Cut-and-paste this out of other source files in the
 225                   tree.
 226
 227                 * Switch statements have the case at the same indentation as the
 228                   switch:
 229
 230                         switch (x) {
 231                         case 'a':
 232                                 ...
 233                         case 'b':
 234                                 ...
 235                         }
 236
 237                 * Large switch statements should have blank lines
 238                   between case statements:
 239
 240                          switch (x) {
 241
 242                          case 'a':
 243                                 large code chunk;
 244
 245                          case 'b':
 246                                 another code chunk;
 247
 248                          default:
 249                                 another code chunk;
 250                          }
 251
 252                 * All method names and properties should be StudlyCapped.
 253
 254                 * Private variable members of a class and function
 255                   local variable names should be under_scored (no
 256                   camelCase please).
 257
 258                 * C# is a pretty verbose and heavily-nested language.  Don't
 259                   worry about trying to fit everything into 80 columns.
 260                   However, don't be afraid to use multiple lines, especially
 261                   with function arguments when it may be easier to read or
 262                   more aesthetic to do so.
 263
 264 * Best practices
 265
 266         * Use String.Empty instead of "" for any comparisons.  This is
 267           because using "" will cause a new string to be allocated,
 268           whereas String.Empty is an interned reference.
 269
 270 If you are using Emacs, you might want to put something like this
 271 in your .emacs file:
 272
 273 (defun poor-mans-csharp-mode ()
 274   (java-mode)
 275   (setq mode-name "C#")
 276   (set-variable 'tab-width 8)
 277   (set-variable 'indent-tabs-mode t)
 278   (set-variable 'c-basic-offset 8)
 279   (c-set-offset 'inline-open 0)
 280   (c-set-offset 'case-label 0)
 281 )
 282
 283 (setq auto-mode-alist (append '(("\\.cs\\'" . poor-mans-csharp-mode))
 284                               auto-mode-alist))
 285