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.
  14
  15
  16 C# Coding Style Guidelines
  17 ==========================
  18
  19 These guidelines should be followed when writing code in Banshee. For the most
  20 part they are similar to the Mono syntax guidelines [1]. All public API must
  21 adhere to the .NET Framework Design Guidelines. [2]
  22
  23 Patches and additions to the code base will be checked for adherence to these
  24 guidelines. If code is in violation, you will be asked to reformat it.
  25
  26   1. Private variable/field names should be written like:
  27
  28       lower_case_with_under_scores
  29
  30   2. Property, event, and method names should be written like:
  31
  32       UpperCaseStartingLetter
  33
  34   3. A space before method/conditional parenthesis, braces:
  35
  36       if (condition) {
  37          CallSomeFunction (args);
  38       }
  39
  40   4. One space before a brace on the same line as a conditional or property:
  41
  42       while (condition) {
  43          ...
  44       }
  45
  46   5. Namespace, Class, Method braces on separate lines:
  47
  48       namespace Foo
  49       {
  50           public class Bar
  51           {
  52               private void Method ()
  53               {
  54                   if (condition) {
  55                       ..
  56                   }
  57               }
  58           }
  59       }
  60
  61   6. The exception to rule 5 is for Properties. The brace in the same line
  62      with the get/set keyword and the respective getter/setter block all
  63      inline, provided the block is simple:
  64
  65       public string Something {
  66           get { return "yay"; }
  67       }
  68
  69   7. If the property accessor block (get/set) is more than one line, use the
  70      alternative syntax:
  71
  72       public string Something {
  73           set {
  74               DoSomething ();
  75               something = value;
  76           }
  77       }
  78
  79   8. There is a space between generic parameters:
  80
  81       Dictionary<K, V> not Dictionary<K,V>
  82
  83   9. Use 4 space characters for indentation, NOT tabs (except in Makefiles)
  84
  85   10. Try to observe a 120 character wrap margin. If your lines are over 120
  86      characters, break and indent them logically.
  87
  88   11. One space at both sides of all type of operators (assignment,
  89      equality, mathematical, event-subscription, ...):
  90
  91       var compare = (a + b * c) != (d - e * f);
  92
  93
  94 .NET API Naming Guidelines
  95 ==========================
  96
  97   1. Member names should be descriptive and it is best to avoid abbreviations
  98      and acronyms
  99
 100   2. If an abbreviation or acronym is used, it should be in the form of an
 101      accepted name that is generally well known
 102
 103   3. If an acronym is one-two characters long, it should be all caps
 104
 105       Banshee.IO and not Banshee.Io
 106
 107   4. If an acronym is three or more characters long, only its first letter
 108      should be capitalized
 109
 110       Banshee.Cdrom
 111       Banshee.Playlists.Formats.Pls
 112       Banshee.Playlists.Formats.M3u
 113
 114   5. Prefix interfaces with 'I'
 115
 116       IPlaylist
 117       IImportable
 118
 119
 120 Implementation Guidelines
 121 =========================
 122
 123   1. Use generics and generic collections when possible in place of
 124      1.0 features. New code in Banshee should leverage 2.0 features
 125      as much as possible, and old code should be updated as development
 126      occurs in a given area.
 127
 128       Use List<T> instead of ArrayList, Dictionary<K, V> instead of Hashtable
 129
 130   2. In *most* cases Banshee.IO should be used (and possibly extended) when
 131      IO must be performed. Do *NOT* hard-code System.IO, Mono.Unix, or
 132      Gnome.Vfs IO into top-level APIs.
 133
 134   3. When a platform-specific task needs to be performed, a top-level,
 135      generic API must be designed first and then the platform implementation
 136      of the API can be added. See Banshee.Configuration for ideas.
 137
 138   4. Do not hard code path separators. Use Path.DirectorySeparatorChar instead
 139      as it is portable to other platforms.
 140
 141   5. Try not to perform many string concatenations. Use a StringBuilder if
 142      necessary
 143
 144   6. Avoid calls to Assembly.GetTypes as memory resulting from these calls
 145      will not be GCed.
 146
 147
 148 Organization Guidelines
 149 =======================
 150
 151   1. Organize code into logical namespaces:
 152
 153       Banshee.Cdrom
 154       Banshee.Cdrom.Gui
 155       Banshee.Cdrom.Nautilus
 156
 157   2. Try to keep GUI as separate as possible from "real work" and keep
 158      the namespace separate as well, if possible and applicable. For instance,
 159      Many different CD-ROM backends could be written for different
 160      platforms, but the same GUI should be used. Don't put GUI code in
 161      the platform implementation:
 162
 163       Banshee.Cdrom
 164       Banshee.Cdrom.Gui
 165       Banshee.Cdrom.Nautilus
 166
 167   3. Banshee's sources are layed out in the following way in the build:
 168
 169      src/<high-level-group>/<assembly-name>/<namespace>/<class-or-interface>.cs
 170
 171   4. Small member definitions (delegates, argument classes, enums) can go
 172      inside the same file containing the primary class, but classes should
 173      generally be in separate files. Use logical grouping with files.
 174
 175
 176 [1] http://www.mono-project.com/Coding_Guidelines
 177 [2] Highly recommended reading: http://www.amazon.com/gp/product/0321246756/ or
 178     view at: http://msdn2.microsoft.com/en-us/library/ms229042.aspx
 179