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 Exception ("Unimplemented");
  38         }
  39
  40 * Tagging buggy code
  41
  42         If there is a bug in your implementation tag the problem by using
  43         the word "FIXME" in the code, together with a description of the
  44         problem.
  45
  46         Do not use XXX or obscure descriptions, because otherwise people
  47         will not be able to understand what you mean.
  48
  49 * Tagging Problematic specs.
  50
  51         If the documentation and the Microsoft implementation do
  52         differ (you wrote a test case to prove this), I suggest that you edit
  53         the file `mcs/class/doc/API-notes' so we can keep track of these problems
  54         and submit our comments to ECMA or Microsoft and seek clarification.
  55
  56         Sometimes the documentation might be buggy, and sometimes the implementation
  57         might be buggy.  Lets try to identify and pinpoint which one
  58         is the correct one.
  59
  60         Sometimes the specification will be lame (consider Version.ToString (fieldCount)
  61         where there is no way of knowing how many fields are available, making the API
  62         not only stupid, but leading to unreliable code).
  63
  64         In those cases, use the keyword "LAMESPEC".
  65
  66
  67 * Coding considerations and style.
  68
  69         In order to keep the code consistent, please use the following
  70         conventions.  From here on `good' and `bad' are used to attribute
  71         things that would make the coding style match, or not match.  It is not
  72         a judgement call on your coding abilities, but more of a style and
  73         look call.  Please try to follow these guidelines to ensure prettiness.
  74
  75         Use 8 space tabs for writing your code (hopefully we can keep
  76         this consistent).  If you are modifying someone else's code, try
  77         to keep the coding style similar.
  78
  79         Since we are using 8-space tabs, you might want to consider the Linus
  80         Torvals trick to reduce code nesting.  Many times in a loop, you will
  81         find yourself doing a test, and if the test is true, you will nest.
  82         Many times this can be changed.  Example:
  83
  84
  85                 for (i = 0; i < 10; i++) {
  86                         if (something (i)) {
  87                                 do_more ();
  88                         }
  89                 }
  90
  91         This take precious space, instead write it like this:
  92
  93                 for (i = 0; i < 10; i++) {
  94                         if (!something (i))
  95                                 continue;
  96                         do_more ();
  97                 }
  98
  99         A few guidelines:
 100
 101                 * Use a space before an opening parenthesis when calling
 102                   functions, like this:
 103
 104                         method (a);
 105
 106                 * Do not put a space after the opening parenthesis and the
 107                   closing one, ie:
 108
 109                         good: method (a);
 110
 111                         bad:  method ( a );
 112
 113                 * Inside a code block, put the opening brace on the same line
 114                   as the statement:
 115
 116                         good:
 117                                 if (a) {
 118                                         code ();
 119                                         code ();
 120                                 }
 121
 122                         bad:
 123                                 if (a)
 124                                 {
 125                                         code ();
 126                                         code ();
 127                                 }
 128
 129                 * Avoid using unecessary open/close braces, vertical space
 130                   is usually limited:
 131
 132                         good:
 133                                 if (a)
 134                                         code ();
 135
 136                         bad:
 137                                 if (a) {
 138                                         code ();
 139                                 }
 140
 141                 * When defining a method, use the C style for brace placement,
 142                   that means, use a new line for the brace, like this:
 143
 144                         good:
 145                                 void Method ()
 146                                 {
 147                                 }
 148
 149                         bad:
 150                                 void Method () {
 151                                 }
 152
 153                 * Properties are an exception, keep the brace on the same line
 154                   as the property declaration.   Rationale: this makes it visually
 155                   simple to distinguish them.
 156
 157                         good:
 158                                 int Property {
 159                                         get {
 160                                                 return value;
 161                                         }
 162                                 }
 163
 164                         bad:
 165                                 int Property
 166                                 {
 167                                         get {
 168                                                 return value;
 169                                         }
 170                                 }
 171
 172                   Notice how the accessor "get" also keeps its brace on the same
 173                   line.
 174
 175                 * Use white space in expressions liberally, except in the presence
 176                   of parenthesis:
 177
 178                         good:
 179
 180                                 if (a + 5 > method (blah () + 4))
 181
 182                         bad:
 183                                 if (a+5>method(blah()+4))
 184
 185                 * For any new files, please use a descriptive introduction, like
 186                   this:
 187
 188                         //
 189                         // System.Comment.cs: Handles comments in System files.
 190                         //
 191                         // Author:
 192                         //   Juan Perez (juan@address.com)
 193                         //
 194                         // (C) 2002 Address, Inc (http://www.address.com)
 195                         //
 196
 197                 * If you are modyfing someone else's code, and your contribution
 198                   is significant, please add yourself to the Authors list.
 199
 200         Here are a couple of examples:
 201
 202 class X : Y {
 203
 204         bool Method (int argument_1, int argument_2)
 205         {
 206                 if (argument_1 == argument_2)
 207                         throw new Exception (Locale.GetText ("They are equal!");
 208
 209                 if (argument_1 < argument_2) {
 210                         if (argument_1 * 3 > 4)
 211                                 return true;
 212                         else
 213                                 return false;
 214                 }
 215
 216                 //
 217                 // This sample helps keep your sanity while using 8-spaces for tabs
 218                 //
 219                 VeryLongIdentifierWhichTakesManyArguments (
 220                         Argument1, Argument2, Argument3,
 221                         NestedCallHere (
 222                                 MoreNested));
 223         }
 224
 225         bool MyProperty {
 226                 get {
 227                         return x;
 228                 }
 229
 230                 set {
 231                         x = value;
 232                 }
 233         }
 234
 235         void AnotherMethod ()
 236         {
 237                 if ((a + 5) != 4) {
 238                 }
 239
 240                 while (blah) {
 241                         if (a)
 242                                 continue;
 243                         b++;
 244                 }
 245         }
 246 }
 247