class/README

   1 The class libraries are grouped together in the assemblies they belong.
   2
   3 Each directory here represents an assembly, and inside each directory we
   4 divide the code based on the namespace they implement.
   5
   6 In addition, each assembly directory contains a Test directory that holds the
   7 NUnit tests for that assembly.
   8
   9 We use a new build system which is described by various README files
  10 in mcs/build
  11
  12 The build process typically builds an assembly, but in some cases it
  13 also builds special versions of the assemblies intended to be used for
  14 testing.
  15
  16 * Missing implementation bits
  17
  18         If you implement a class and you are missing implementation bits,
  19         please use the attribute [MonoTODO].  This attribute can be used
  20         to programatically generate our status web pages:
  21
  22         [MonoTODO]
  23         int MyFunction ()
  24         {
  25                 throw new NotImplementedException ();
  26         }
  27
  28         Ideally, write a human description of the reason why there is
  29         a MonoTODO, this will be useful in the future for our
  30         automated tools that can assist in developers porting their
  31         code.
  32
  33         Do not use MonoTODO attributes for reminding yourself of
  34         internal changes that must be done. Use FIXMEs or other kinds
  35         of comments in the source code for that purpose, and if the
  36         problem requires to be followed up on, file a bug.
  37
  38 * Supporting .NET 1.2, .NET 1.1 and .NET 1.0 builds
  39
  40         The defines NET_1_1 and NET_2_0 are used to include
  41         features.   When NET_2_0 is defined, it also implies that the
  42         NET_1_1 is defined.
  43
  44         To have code which is only available in an old version, use ONLY_1_0,
  45         ONLY_1_1
  46
  47 * Tagging buggy code
  48
  49         If there is a bug in your implementation tag the problem by using
  50         the word "FIXME" in the code, together with a description of the
  51         problem.
  52
  53         Do not use XXX or obscure descriptions, because otherwise people
  54         will not be able to understand what you mean.
  55
  56 * Tagging Problematic specs.
  57
  58         If the documentation and the Microsoft implementation do
  59         differ (you wrote a test case to prove this), I suggest that you edit
  60         the file `mcs/class/doc/API-notes' so we can keep track of these problems
  61         and submit our comments to ECMA or Microsoft and seek clarification.
  62
  63         Sometimes the documentation might be buggy, and sometimes the implementation
  64         might be buggy.  Lets try to identify and pinpoint which one
  65         is the correct one.
  66
  67         Sometimes the specification will be lame (consider Version.ToString (fieldCount)
  68         where there is no way of knowing how many fields are available, making the API
  69         not only stupid, but leading to unreliable code).
  70
  71         In those cases, use the keyword "LAMESPEC".
  72
  73
  74 * Coding considerations and style.
  75
  76         In order to keep the code consistent, please use the following
  77         conventions.  From here on `good' and `bad' are used to attribute
  78         things that would make the coding style match, or not match.  It is not
  79         a judgement call on your coding abilities, but more of a style and
  80         look call.  Please try to follow these guidelines to ensure prettiness.
  81
  82         Use 8 space tabs for writing your code (hopefully we can keep
  83         this consistent).  If you are modifying someone else's code, try
  84         to keep the coding style similar.
  85
  86         Since we are using 8-space tabs, you might want to consider the Linus
  87         Torvals trick to reduce code nesting.  Many times in a loop, you will
  88         find yourself doing a test, and if the test is true, you will nest.
  89         Many times this can be changed.  Example:
  90
  91
  92                 for (i = 0; i < 10; i++) {
  93                         if (something (i)) {
  94                                 do_more ();
  95                         }
  96                 }
  97
  98         This take precious space, instead write it like this:
  99
 100                 for (i = 0; i < 10; i++) {
 101                         if (!something (i))
 102                                 continue;
 103                         do_more ();
 104                 }
 105
 106         A few guidelines:
 107
 108                 * Use a space before an opening parenthesis when calling
 109                   functions, or indexing, like this:
 110
 111                         method (a);
 112                         b [10];
 113
 114                 * Do not put a space after the opening parenthesis and the
 115                   closing one, ie:
 116
 117                         good: method (a);       array [10];
 118
 119                         bad:  method ( a );     array[ 10 ];
 120
 121                 * Inside a code block, put the opening brace on the same line
 122                   as the statement:
 123
 124                         good:
 125                                 if (a) {
 126                                         code ();
 127                                         code ();
 128                                 }
 129
 130                         bad:
 131                                 if (a)
 132                                 {
 133                                         code ();
 134                                         code ();
 135                                 }
 136
 137                 * Avoid using unecessary open/close braces, vertical space
 138                   is usually limited:
 139
 140                         good:
 141                                 if (a)
 142                                         code ();
 143
 144                         bad:
 145                                 if (a) {
 146                                         code ();
 147                                 }
 148
 149                 * When defining a method, use the C style for brace placement,
 150                   that means, use a new line for the brace, like this:
 151
 152                         good:
 153                                 void Method ()
 154                                 {
 155                                 }
 156
 157                         bad:
 158                                 void Method () {
 159                                 }
 160
 161                 * Properties and indexers are an exception, keep the
 162                   brace on the same line as the property declaration.
 163                   Rationale: this makes it visually
 164                   simple to distinguish them.
 165
 166                         good:
 167                                 int Property {
 168                                         get {
 169                                                 return value;
 170                                         }
 171                                 }
 172
 173                         bad:
 174                                 int Property
 175                                 {
 176                                         get {
 177                                                 return value;
 178                                         }
 179                                 }
 180
 181                   Notice how the accessor "get" also keeps its brace on the same
 182                   line.
 183
 184                   For very small properties, you can compress things:
 185
 186                         ok:
 187                                 int Property {
 188                                         get { return value; }
 189                                         set { x = value; }
 190                                 }
 191
 192                 * Use white space in expressions liberally, except in the presence
 193                   of parenthesis:
 194
 195                         good:
 196
 197                                 if (a + 5 > method (blah () + 4))
 198
 199                         bad:
 200                                 if (a+5>method(blah()+4))
 201
 202                 * For any new files, please use a descriptive introduction, like
 203                   this:
 204
 205                         //
 206                         // System.Comment.cs: Handles comments in System files.
 207                         //
 208                         // Author:
 209                         //   Juan Perez (juan@address.com)
 210                         //
 211                         // (C) 2002 Address, Inc (http://www.address.com)
 212                         //
 213
 214                 * If you are modyfing someone else's code, and your contribution
 215                   is significant, please add yourself to the Authors list.
 216
 217                 * Switch statements have the case at the same indentation as the
 218                   switch:
 219
 220                         switch (x) {
 221                         case 'a':
 222                                 ...
 223                         case 'b':
 224                                 ...
 225                         }
 226
 227                 * Argument names should use the camel casing for
 228                   identifiers, like this:
 229
 230                         good:
 231                                 void Method (string myArgument)
 232
 233                         bad:
 234                                 void Method (string lpstrArgument)
 235                                 void Method (string my_string)
 236
 237                 * Empty methods: They should have the body of code using two
 238                   lines, in consistency with the rest:
 239
 240                         good:
 241                                 void EmptyMethod ()
 242                                 {
 243                                 }
 244
 245                         bad:
 246                                 void EmptyMethod () {}
 247
 248                                 void EmptyMethod ()
 249                                 {}
 250
 251                 * Line length: The line length for C# source code is 134 columns.
 252
 253
 254                   If your function declaration arguments go beyond
 255                   this point, please align your arguments to match the
 256                   opening brace, like this:
 257
 258                         void Function (int arg, string argb,
 259                                        int argc)
 260                         {
 261                         }
 262
 263                   When invoking functions, the rule is different, the
 264                   arguments are not aligned with the previous
 265                   argument, instead they begin at the tabbed position,
 266                   like this:
 267
 268                         void M ()
 269                         {
 270                                 MethodCall ("Very long string that will force",
 271                                         "Next argument on the 8-tab pos",
 272                                         "Just like this one")
 273
 274                         }
 275
 276         Here are a couple of examples:
 277
 278 class X : Y {
 279
 280         bool Method (int argument_1, int argument_2)
 281         {
 282                 if (argument_1 == argument_2)
 283                         throw new Exception (Locale.GetText ("They are equal!");
 284
 285                 if (argument_1 < argument_2) {
 286                         if (argument_1 * 3 > 4)
 287                                 return true;
 288                         else
 289                                 return false;
 290                 }
 291
 292                 //
 293                 // This sample helps keep your sanity while using 8-spaces for tabs
 294                 //
 295                 VeryLongIdentifierWhichTakesManyArguments (
 296                         Argument1, Argument2, Argument3,
 297                         NestedCallHere (
 298                                 MoreNested));
 299         }
 300
 301         bool MyProperty {
 302                 get {
 303                         return x;
 304                 }
 305
 306                 set {
 307                         x = value;
 308                 }
 309         }
 310
 311         void AnotherMethod ()
 312         {
 313                 if ((a + 5) != 4) {
 314                 }
 315
 316                 while (blah) {
 317                         if (a)
 318                                 continue;
 319                         b++;
 320                 }
 321         }
 322 }
 323