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