mcs/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 The nant build file for an assembly creates two versions of the dll for that
  10 assembly. One version is a "full" dll.  The full dll contains (almost) all
  11 of the classes, regardless of how complete the classes are. The name of this
  12 dll is the normal name you would expect, like "corlib.dll" or "System.dll".
  13 These full dll's are created in the /mcs/class/lib directory.
  14
  15 The other dll which is built is a "restricted" dll.  The restricted dll
  16 omits incomplete classes that would prevent the NUnit testrunner from actually
  17 running the tests. These restricted dll's are created in the Test directory
  18 of their respective assembly and named with a "_res" suffix.  So, for example,
  19 the NUnit-testable dll for corlib is /mcs/class/corlib/Test/corlib_res.dll.
  20
  21 The final dll which is built is the one which houses the actual NUnit tests.
  22 This dll is built from all of the classes in the Test directory and below, and
  23 is named with a "_test" suffix. So, for example, the NUnit tests for corlib
  24 are in /mcs/class/corlib/Test/corlib_test.dll. This dll is also linked with
  25 the restricted dll found in the same directory.
  26
  27
  28 * Missing implementation bits
  29
  30         If you implement a class and you are missing implementation bits,
  31         please use the attribute [MonoTODO].  This attribute can be used
  32         to programatically generate our status web pages:
  33
  34         [MonoTODO]
  35         int MyFunction ()
  36         {
  37                 throw new NotImplementedException ();
  38         }
  39
  40 * Supporting both .NET 1.1 and .NET 1.0 builds
  41
  42         Use #ifdef NET_1_1 for code that should only be included for
  43         a .NET 1.1 build, and NET_1_0 for code that should only be included
  44         for a 1.0 build.
  45
  46 * Tagging buggy code
  47
  48         If there is a bug in your implementation tag the problem by using
  49         the word "FIXME" in the code, together with a description of the
  50         problem.
  51
  52         Do not use XXX or obscure descriptions, because otherwise people
  53         will not be able to understand what you mean.
  54
  55 * Tagging Problematic specs.
  56
  57         If the documentation and the Microsoft implementation do
  58         differ (you wrote a test case to prove this), I suggest that you edit
  59         the file `mcs/class/doc/API-notes' so we can keep track of these problems
  60         and submit our comments to ECMA or Microsoft and seek clarification.
  61
  62         Sometimes the documentation might be buggy, and sometimes the implementation
  63         might be buggy.  Lets try to identify and pinpoint which one
  64         is the correct one.
  65
  66         Sometimes the specification will be lame (consider Version.ToString (fieldCount)
  67         where there is no way of knowing how many fields are available, making the API
  68         not only stupid, but leading to unreliable code).
  69
  70         In those cases, use the keyword "LAMESPEC".
  71
  72
  73 * Coding considerations and style.
  74
  75         In order to keep the code consistent, please use the following
  76         conventions.  From here on `good' and `bad' are used to attribute
  77         things that would make the coding style match, or not match.  It is not
  78         a judgement call on your coding abilities, but more of a style and
  79         look call.  Please try to follow these guidelines to ensure prettiness.
  80
  81         Use 8 space tabs for writing your code (hopefully we can keep
  82         this consistent).  If you are modifying someone else's code, try
  83         to keep the coding style similar.
  84
  85         Since we are using 8-space tabs, you might want to consider the Linus
  86         Torvals trick to reduce code nesting.  Many times in a loop, you will
  87         find yourself doing a test, and if the test is true, you will nest.
  88         Many times this can be changed.  Example:
  89
  90
  91                 for (i = 0; i < 10; i++) {
  92                         if (something (i)) {
  93                                 do_more ();
  94                         }
  95                 }
  96
  97         This take precious space, instead write it like this:
  98
  99                 for (i = 0; i < 10; i++) {
 100                         if (!something (i))
 101                                 continue;
 102                         do_more ();
 103                 }
 104
 105         A few guidelines:
 106
 107                 * Use a space before an opening parenthesis when calling
 108                   functions, or indexing, like this:
 109
 110                         method (a);
 111                         b [10];
 112
 113                 * Do not put a space after the opening parenthesis and the
 114                   closing one, ie:
 115
 116                         good: method (a);       array [10];
 117
 118                         bad:  method ( a );     array[ 10 ];
 119
 120                 * Inside a code block, put the opening brace on the same line
 121                   as the statement:
 122
 123                         good:
 124                                 if (a) {
 125                                         code ();
 126                                         code ();
 127                                 }
 128
 129                         bad:
 130                                 if (a)
 131                                 {
 132                                         code ();
 133                                         code ();
 134                                 }
 135
 136                 * Avoid using unecessary open/close braces, vertical space
 137                   is usually limited:
 138
 139                         good:
 140                                 if (a)
 141                                         code ();
 142
 143                         bad:
 144                                 if (a) {
 145                                         code ();
 146                                 }
 147
 148                 * When defining a method, use the C style for brace placement,
 149                   that means, use a new line for the brace, like this:
 150
 151                         good:
 152                                 void Method ()
 153                                 {
 154                                 }
 155
 156                         bad:
 157                                 void Method () {
 158                                 }
 159
 160                 * Properties and indexers are an exception, keep the
 161                   brace on the same line as the property declaration.
 162                   Rationale: this makes it visually
 163                   simple to distinguish them.
 164
 165                         good:
 166                                 int Property {
 167                                         get {
 168                                                 return value;
 169                                         }
 170                                 }
 171
 172                         bad:
 173                                 int Property
 174                                 {
 175                                         get {
 176                                                 return value;
 177                                         }
 178                                 }
 179
 180                   Notice how the accessor "get" also keeps its brace on the same
 181                   line.
 182
 183                   For very small properties, you can compress things:
 184
 185                         ok:
 186                                 int Property {
 187                                         get { return value; }
 188                                         set { x = value; }
 189                                 }
 190
 191                 * Use white space in expressions liberally, except in the presence
 192                   of parenthesis:
 193
 194                         good:
 195
 196                                 if (a + 5 > method (blah () + 4))
 197
 198                         bad:
 199                                 if (a+5>method(blah()+4))
 200
 201                 * For any new files, please use a descriptive introduction, like
 202                   this:
 203
 204                         //
 205                         // System.Comment.cs: Handles comments in System files.
 206                         //
 207                         // Author:
 208                         //   Juan Perez (juan@address.com)
 209                         //
 210                         // (C) 2002 Address, Inc (http://www.address.com)
 211                         //
 212
 213                 * If you are modyfing someone else's code, and your contribution
 214                   is significant, please add yourself to the Authors list.
 215
 216                 * Switch statements have the case at the same indentation as the
 217                   switch:
 218
 219                         switch (x) {
 220                         case 'a':
 221                                 ...
 222                         case 'b':
 223                                 ...
 224                         }
 225
 226                 * Argument names should use the camel casing for
 227                   identifiers, like this:
 228
 229                         good:
 230                                 void Method (string myArgument)
 231
 232                         bad:
 233                                 void Method (string lpstrArgument)
 234                                 void Method (string my_string)
 235
 236         Here are a couple of examples:
 237
 238 class X : Y {
 239
 240         bool Method (int argument_1, int argument_2)
 241         {
 242                 if (argument_1 == argument_2)
 243                         throw new Exception (Locale.GetText ("They are equal!");
 244
 245                 if (argument_1 < argument_2) {
 246                         if (argument_1 * 3 > 4)
 247                                 return true;
 248                         else
 249                                 return false;
 250                 }
 251
 252                 //
 253                 // This sample helps keep your sanity while using 8-spaces for tabs
 254                 //
 255                 VeryLongIdentifierWhichTakesManyArguments (
 256                         Argument1, Argument2, Argument3,
 257                         NestedCallHere (
 258                                 MoreNested));
 259         }
 260
 261         bool MyProperty {
 262                 get {
 263                         return x;
 264                 }
 265
 266                 set {
 267                         x = value;
 268                 }
 269         }
 270
 271         void AnotherMethod ()
 272         {
 273                 if ((a + 5) != 4) {
 274                 }
 275
 276                 while (blah) {
 277                         if (a)
 278                                 continue;
 279                         b++;
 280                 }
 281         }
 282 }
 283