HACKING - cdhowie-clone in Banshee

This document defines many guidelines that should be adhered to when developing 
against Banshee. These guidelines will make the codebase more readable,
extensible, and portable.

ChangeLog Formatting Guidelines
===============================

Every change to source code must have an entry in the ChangeLog file. The
formatting details of this file are described here:

  http://banshee-project.org/ChangeLogForDevelopers

Please review these guidelines separate to this document.


C# Coding Style Guidelines
==========================

These guidelines should be followed when writing code in Banshee. For the most
part they are similar to the Mono syntax guidelines [1]. All public API must
adhere to the .NET Framework Design Guidelines. [2]

Patches and additions to the code base will be checked for adherence to these
guidelines. If code is in violation, you will be asked to reformat it.

  1. Private variable/field names should be written like:

      lower_case_with_under_scores

  2. Property, event, and method names should be written like:

      UpperCaseStartingLetter

  3. A space before method/conditional parenthesis, braces:

      if (condition) {
         CallSomeFunction (args);
      }

  4. One space before a brace on the same line as a conditional or property:

      while (condition) {
         ...
      }

  5. Namespace, Class, Method braces on separate lines:

      namespace Foo
      {
          public class Bar
          {
              private void Method ()
              {
                  if (condition) {
                      ..
                  }
              }
          }
      }

  6. The exception to rule 5 is for Properties. The brace in the same line
     with the get/set keyword and the respective getter/setter block all
     inline, provided the block is simple:

      public string Something {
          get { return "yay"; }
      }

  7. If the property accessor block (get/set) is more than one line, use the
     alternative syntax:
     
      public string Something {
          set {
              DoSomething ();
              something = value;
          }
      }

  8. There is a space between generic parameters:

      Dictionary<K, V> not Dictionary<K,V>

  9. Use 4 space characters for indention, NOT tabs
   
  10. Try to observe a 120 character wrap margin. If your lines are over 120
     characters, break and indent them logically.


.NET API Naming Guidelines
==========================

  1. Member names should be descriptive and it is best to avoid abbreviations
     and acronyms

  2. If an abbreviation or acronym is used, it should be in the form of an 
     accepted name that is generally well known

  3. If an acronym is one-two characters long, it should be all caps 

      Banshee.IO and not Banshee.Io

  4. If an acronym is three or more characters long, only its first letter
     should be capitalized

      Banshee.Cdrom
      Banshee.Playlists.Formats.Pls
      Banshee.Playlists.Formats.M3u

  5. Prefix interfaces with 'I'

      IPlaylist
      IImportable


Implementation Guidelines
=========================

  1. Use generics and generic collections when possible in place of 
     1.0 features. New code in Banshee should leverage 2.0 features 
     as much as possible, and old code should be updated as development
     occurs in a given area.

      Use List<T> instead of ArrayList, Dictionary<K, V> instead of Hashtable

  2. In *most* cases Banshee.IO should be used (and possibly extended) when
     IO must be performed. Do *NOT* hard-code System.IO, Mono.Unix, or
     Gnome.Vfs IO into top-level APIs.

  3. When a platform-specific task needs to be performed, a top-level, 
     generic API must be designed first and then the platform implementation
     of the API can be added. See Banshee.Cdrom for ideas.
   
  4. Do not hard code path separators. Use Path.DirectorySeparatorChar instead
     as it is portable to other platforms. 

  5. Try not to perform many string concatenations. Use a StringBuilder if
     necessary
   
  6. Avoid calls to Assembly.GetTypes as memory resulting from these calls
     will not be GCed.


Organization Guidelines
=======================

  1. Organize code into logical namespaces:

      Banshee.Cdrom
      Banshee.Cdrom.Gui
      Banshee.Cdrom.Nautilus

  2. Try to keep GUI as separate as possible from "real work" and keep
     the namespace separate as well, if possible and applicable. For instance,
     Many different CD-ROM backends could be written for different 
     platforms, but the same GUI should be used. Don't put GUI code in
     the platform implementation:

      Banshee.Cdrom
      Banshee.Cdrom.Gui
      Banshee.Cdrom.Nautilus

  3. Banshee's sources are layed out in the following way in the build [3]:

     src/<assembly-name>/<namespace>/<class-or-interface>.cs

  4. Small member definitions (delegates, argument classes, enums) can go
     inside the same file containing the primary class, but classes should
     generally be in separate files. Use logical grouping with files.


[1] http://www.mono-project.com/Coding_Guidelines
[2] Highly recommended reading: http://www.amazon.com/gp/product/0321246756/ or
    view at: http://msdn2.microsoft.com/en-us/library/ms229042.aspx
[3] This layout pattern is to be followed for new code, but due to limitations
    with GNOME CVS, the older/deprecated directory/file layout is still in
    use too. When GNOME CVS is migrated to Subversion, the entire tree will
    be restructured to reflect this naming/layout convention.

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	ChangeLog Formatting Guidelines
6	===============================
7
8	Every change to source code must have an entry in the ChangeLog file. The
9	formatting details of this file are described here:
10
11	http://banshee-project.org/ChangeLogForDevelopers
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 indention, NOT tabs
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
89	.NET API Naming Guidelines
90	==========================
91
92	1. Member names should be descriptive and it is best to avoid abbreviations
93	and acronyms
94
95	2. If an abbreviation or acronym is used, it should be in the form of an
96	accepted name that is generally well known
97
98	3. If an acronym is one-two characters long, it should be all caps
99
100	Banshee.IO and not Banshee.Io
101
102	4. If an acronym is three or more characters long, only its first letter
103	should be capitalized
104
105	Banshee.Cdrom
106	Banshee.Playlists.Formats.Pls
107	Banshee.Playlists.Formats.M3u
108
109	5. Prefix interfaces with 'I'
110
111	IPlaylist
112	IImportable
113
114
115	Implementation Guidelines
116	=========================
117
118	1. Use generics and generic collections when possible in place of
119	1.0 features. New code in Banshee should leverage 2.0 features
120	as much as possible, and old code should be updated as development
121	occurs in a given area.
122
123	Use List<T> instead of ArrayList, Dictionary<K, V> instead of Hashtable
124
125	2. In most cases Banshee.IO should be used (and possibly extended) when
126	IO must be performed. Do NOT hard-code System.IO, Mono.Unix, or
127	Gnome.Vfs IO into top-level APIs.
128
129	3. When a platform-specific task needs to be performed, a top-level,
130	generic API must be designed first and then the platform implementation
131	of the API can be added. See Banshee.Cdrom for ideas.
132
133	4. Do not hard code path separators. Use Path.DirectorySeparatorChar instead
134	as it is portable to other platforms.
135
136	5. Try not to perform many string concatenations. Use a StringBuilder if
137	necessary
138
139	6. Avoid calls to Assembly.GetTypes as memory resulting from these calls
140	will not be GCed.
141
142
143	Organization Guidelines
144	=======================
145
146	1. Organize code into logical namespaces:
147
148	Banshee.Cdrom
149	Banshee.Cdrom.Gui
150	Banshee.Cdrom.Nautilus
151
152	2. Try to keep GUI as separate as possible from "real work" and keep
153	the namespace separate as well, if possible and applicable. For instance,
154	Many different CD-ROM backends could be written for different
155	platforms, but the same GUI should be used. Don't put GUI code in
156	the platform implementation:
157
158	Banshee.Cdrom
159	Banshee.Cdrom.Gui
160	Banshee.Cdrom.Nautilus
161
162	3. Banshee's sources are layed out in the following way in the build [3]:
163
164	src/<assembly-name>/<namespace>/<class-or-interface>.cs
165
166	4. Small member definitions (delegates, argument classes, enums) can go
167	inside the same file containing the primary class, but classes should
168	generally be in separate files. Use logical grouping with files.
169
170
171	[1] http://www.mono-project.com/Coding_Guidelines
172	[2] Highly recommended reading: http://www.amazon.com/gp/product/0321246756/ or
173	view at: http://msdn2.microsoft.com/en-us/library/ms229042.aspx
174	[3] This layout pattern is to be followed for new code, but due to limitations
175	with GNOME CVS, the older/deprecated directory/file layout is still in
176	use too. When GNOME CVS is migrated to Subversion, the entire tree will
177	be restructured to reflect this naming/layout convention.

Gitorious