HACKING

   1 This document defines many guidelines that should be adhered to when developing
   2 against Banshee. These guidelines will make the codebase more readable,
   3 extensible, and portable.
   4
   5 Commit Message Guidelines
   6 =========================
   7
   8 Every change to source code must have a commit message associated to it. The
   9 formatting details of this message are described here:
  10
  11   http://live.gnome.org/Git/CommitMessages
  12
  13 Please review these guidelines separate to this document, and take in account
  14 these policies on top:
  15
  16   1. Unlike many other open-source projects, we don't use the git tagging
  17      'Signed-off-by' to refer as a licencing statement of a contribution,
  18      rather we use it as 'Reviewed by this maintainer' metadata.
  19
  20   2. As a consequence of the above, the choice of licencing attribution
  21      is implicit: by contributing a patch to the Banshee project you are
  22      automatically accepting to follow the same licence as the project
  23      itself (see our COPYING file) unless stated on the contrary.
  24
  25   3. When a contributed patch contains new files, please include licence
  26      headers in each of them, in the same way the rest of the files of
  27      the projects already have.
  28
  29   4. It's recommended that you add yourself (or your company) to the list
  30      of the copyright owners of a file if you're modifying a considerable
  31      proportion of it.
  32
  33
  34 C# Coding Style Guidelines
  35 ==========================
  36
  37 These guidelines should be followed when writing code in Banshee. For the most
  38 part they are similar to the Mono syntax guidelines [1]. All public API must
  39 adhere to the .NET Framework Design Guidelines. [2]
  40
  41 Patches and additions to the code base will be checked for adherence to these
  42 guidelines. If code is in violation, you will be asked to reformat it.
  43
  44   1. Private variable/field names should be written like:
  45
  46       lower_case_with_under_scores
  47
  48   2. Property, event, and method names should be written like:
  49
  50       UpperCaseStartingLetter
  51
  52   3. A space before method/conditional parenthesis, braces:
  53
  54       if (condition) {
  55          CallSomeFunction (args);
  56       }
  57
  58   4. One space before a brace on the same line as a conditional or property:
  59
  60       while (condition) {
  61          ...
  62       }
  63
  64   5. Namespace, Class, Method braces on separate lines:
  65
  66       namespace Foo
  67       {
  68           public class Bar
  69           {
  70               private void Method ()
  71               {
  72                   if (condition) {
  73                       ..
  74                   }
  75               }
  76           }
  77       }
  78
  79   6. The exception to rule 5 is for Properties. The brace in the same line
  80      with the get/set keyword and the respective getter/setter block all
  81      inline, provided the block is simple:
  82
  83       public string Something {
  84           get { return "yay"; }
  85       }
  86
  87   7. If the property accessor block (get/set) is more than one line, use the
  88      alternative syntax:
  89
  90       public string Something {
  91           set {
  92               DoSomething ();
  93               something = value;
  94           }
  95       }
  96
  97   8. There is a space between generic parameters:
  98
  99       Dictionary<K, V> not Dictionary<K,V>
 100
 101   9. Use 4 space characters for indentation, NOT tabs (except in Makefiles)
 102
 103   10. Try to observe a 120 character wrap margin. If your lines are over 120
 104      characters, break and indent them logically.
 105
 106   11. One space at both sides of all type of operators (assignment,
 107      equality, mathematical, event-subscription, ...):
 108
 109       var compare = (a + b * c) != (d - e * f);
 110
 111   12. Please write `private` accessors even if the language defaults
 112     to it in the context you're in.
 113
 114   13. For tests, use the Assert.That(actual, Is.EqualTo(expected)); syntax,
 115       which is more readable, and prevents you from misplacing the expected
 116       parameter in the place of the actual parameter (a mistake that is very
 117       usual when using the older Assert.AreEqual(,) syntax).
 118
 119   14. Parameter names should be written like:
 120
 121       camelCaseWord
 122
 123
 124 .NET API Naming Guidelines
 125 ==========================
 126
 127   1. Member names should be descriptive and it is best to avoid abbreviations
 128      and acronyms
 129
 130   2. If an abbreviation or acronym is used, it should be in the form of an
 131      accepted name that is generally well known
 132
 133   3. If an acronym is one-two characters long, it should be all caps
 134
 135       Banshee.IO and not Banshee.Io
 136
 137   4. If an acronym is three or more characters long, only its first letter
 138      should be capitalized
 139
 140       Banshee.Cdrom
 141       Banshee.Playlists.Formats.Pls
 142       Banshee.Playlists.Formats.M3u
 143
 144   5. Prefix interfaces with 'I'
 145
 146       IPlaylist
 147       IImportable
 148
 149
 150 Implementation Guidelines
 151 =========================
 152
 153   1. Use generics and generic collections when possible in place of
 154      1.0 features. New code in Banshee should leverage 2.0 features
 155      as much as possible, and old code should be updated as development
 156      occurs in a given area.
 157
 158       Use List<T> instead of ArrayList, Dictionary<K, V> instead of Hashtable
 159
 160   2. In *most* cases Banshee.IO should be used (and possibly extended) when
 161      IO must be performed. Do *NOT* hard-code System.IO, Mono.Unix, or
 162      Gnome.Vfs IO into top-level APIs.
 163
 164   3. When a platform-specific task needs to be performed, a top-level,
 165      generic API must be designed first and then the platform implementation
 166      of the API can be added. See Banshee.Configuration for ideas.
 167
 168   4. Do not hard code path separators. Use Path.DirectorySeparatorChar instead
 169      as it is portable to other platforms.
 170
 171   5. Try not to perform many string concatenations. Use a StringBuilder if
 172      necessary
 173
 174   6. Avoid calls to Assembly.GetTypes as memory resulting from these calls
 175      will not be GCed.
 176
 177
 178 Organization Guidelines
 179 =======================
 180
 181   1. Organize code into logical namespaces:
 182
 183       Banshee.Cdrom
 184       Banshee.Cdrom.Gui
 185       Banshee.Cdrom.Nautilus
 186
 187   2. Try to keep GUI as separate as possible from "real work" and keep
 188      the namespace separate as well, if possible and applicable. For instance,
 189      Many different CD-ROM backends could be written for different
 190      platforms, but the same GUI should be used. Don't put GUI code in
 191      the platform implementation:
 192
 193       Banshee.Cdrom
 194       Banshee.Cdrom.Gui
 195       Banshee.Cdrom.Nautilus
 196
 197   3. Banshee's sources are layed out in the following way in the build:
 198
 199      src/<high-level-group>/<assembly-name>/<namespace>/<class-or-interface>.cs
 200
 201   4. Small member definitions (delegates, argument classes, enums) can go
 202      inside the same file containing the primary class, but classes should
 203      generally be in separate files. Use logical grouping with files.
 204
 205
 206 [1] http://www.mono-project.com/Coding_Guidelines
 207 [2] Highly recommended reading: http://www.amazon.com/gp/product/0321246756/ or
 208     view at: http://msdn2.microsoft.com/en-us/library/ms229042.aspx
 209