X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=mcs%2FCodingStyle;h=8c0ac1e65e1b989757c9545c6710c31cab93fee5;hb=c6d92b9983868483ec4b39b83341ffb413ad74d6;hp=aa78389f7b7d05d136764df67ef9e87fbc554fc5;hpb=669beaed8380fa592533c8755f72593b4422d01d;p=mono.git diff --git a/mcs/CodingStyle b/mcs/CodingStyle index aa78389f7b7..8c0ac1e65e1 100644 --- a/mcs/CodingStyle +++ b/mcs/CodingStyle @@ -1,516 +1 @@ -* Coding Style for the Mono C# source code. - -* Class Libraries and Assembly Layout - - The class libraries are grouped together in the assemblies - they belong. - - Each directory here represents an assembly, and inside each - directory we divide the code based on the namespace they - implement. - - In addition, each assembly directory contains a Test directory - that holds the NUnit tests for that assembly. - - We use a new build system which is described by various README - files in mcs/build - - The build process typically builds an assembly, but in some - cases it also builds special versions of the assemblies - intended to be used for testing. - -* Missing implementation bits - - If you implement a class and you are missing implementation bits, - please use the attribute [MonoTODO]. This attribute can be used - to programatically generate our status web pages: - - [MonoTODO("My Function is not available on Mono")] - int MyFunction () - { - throw new NotImplementedException (); - } - - Ideally, write a human description of the reason why there is - a MonoTODO, this will be useful in the future for our - automated tools that can assist in developers porting their code. - -* Supporting .NET 1.2, .NET 1.1 and .NET 1.0 builds - - The defines NET_1_1 and NET_2_0 are used to include - features. When NET_2_0 is defined, it also implies that the - NET_1_1 is defined. - - To have code which is only available in an old version, use ONLY_1_0, - ONLY_1_1 - -* Tagging buggy code - - If there is a bug in your implementation tag the problem by using - the word "FIXME" in the code, together with a description of the - problem. - - Do not use XXX or obscure descriptions, because otherwise people - will not be able to understand what you mean. - -* Tagging Problematic specs. - - If the documentation and the Microsoft implementation do - differ (you wrote a test case to prove this), I suggest that you edit - the file `mcs/class/doc/API-notes' so we can keep track of these problems - and submit our comments to ECMA or Microsoft and seek clarification. - - Sometimes the documentation might be buggy, and sometimes the implementation - might be buggy. Lets try to identify and pinpoint which one - is the correct one. - - Sometimes the specification will be lame (consider Version.ToString (fieldCount) - where there is no way of knowing how many fields are available, making the API - not only stupid, but leading to unreliable code). - - In those cases, use the keyword "LAMESPEC". - - -* Coding considerations and style. - - In order to keep the code consistent, please use the following - conventions. From here on `good' and `bad' are used to attribute - things that would make the coding style match, or not match. It is not - a judgement call on your coding abilities, but more of a style and - look call. Please try to follow these guidelines to ensure prettiness. - - Use 8 space tabs for writing your code (hopefully we can keep - this consistent). If you are modifying someone else's code, try - to keep the coding style similar. - - Since we are using 8-space tabs, you might want to consider the Linus - Torvals trick to reduce code nesting. Many times in a loop, you will - find yourself doing a test, and if the test is true, you will nest. - Many times this can be changed. Example: - - - for (i = 0; i < 10; i++) { - if (something (i)) { - do_more (); - } - } - - This take precious space, instead write it like this: - - for (i = 0; i < 10; i++) { - if (!something (i)) - continue; - do_more (); - } - -* Performance and readability - - It is more important to be correct than to be fast. - - It is more important to be maintainable than to be fast. - - Fast code that is difficult to maintain is likely going to - be looked down upon. - -* Style Guidelines - - * Use a space before an opening parenthesis when calling - functions, or indexing, like this: - - method (a); - b [10]; - - * Do not put a space after the opening parenthesis and the - closing one, ie: - - good: method (a); array [10]; - - bad: method ( a ); array[ 10 ]; - - * Inside a code block, put the opening brace on the same line - as the statement: - - good: - if (a) { - code (); - code (); - } - - bad: - if (a) - { - code (); - code (); - } - - * Avoid using unecessary open/close braces, vertical space - is usually limited: - - good: - if (a) - code (); - - bad: - if (a) { - code (); - } - - * When defining a method, use the C style for brace placement, - that means, use a new line for the brace, like this: - - good: - void Method () - { - } - - bad: - void Method () { - } - - * Properties and indexers are an exception, keep the - brace on the same line as the property declaration. - Rationale: this makes it visually - simple to distinguish them. - - good: - int Property { - get { - return value; - } - } - - bad: - int Property - { - get { - return value; - } - } - - Notice how the accessor "get" also keeps its brace on the same - line. - - For very small properties, you can compress things: - - ok: - int Property { - get { return value; } - set { x = value; } - } - - * Use white space in expressions liberally, except in the presence - of parenthesis: - - good: - - if (a + 5 > method (blah () + 4)) - - bad: - if (a+5>method(blah()+4)) - - * For any new files, please use a descriptive introduction, like - this: - - // - // System.Comment.cs: Handles comments in System files. - // - // Author: - // Juan Perez (juan@address.com) - // - // (C) 2002 Address, Inc (http://www.address.com) - // - - * If you are modyfing someone else's code, and your contribution - is significant, please add yourself to the Authors list. - - * Switch statements have the case at the same indentation as the - switch: - - switch (x) { - case 'a': - ... - case 'b': - ... - } - - * Argument names should use the camel casing for - identifiers, like this: - - good: - void Method (string myArgument) - - bad: - void Method (string lpstrArgument) - void Method (string my_string) - - * Empty methods: They should have the body of code using two - lines, in consistency with the rest: - - good: - void EmptyMethod () - { - } - - bad: - void EmptyMethod () {} - - void EmptyMethod () - {} - - * Line length: The line length for C# source code is 134 columns. - - - If your function declaration arguments go beyond - this point, please align your arguments to match the - opening brace, like this: - - void Function (int arg, string argb, - int argc) - { - } - - When invoking functions, the rule is different, the - arguments are not aligned with the previous - argument, instead they begin at the tabbed position, - like this: - - void M () - { - MethodCall ("Very long string that will force", - "Next argument on the 8-tab pos", - "Just like this one") - - } - - * Variable declaration indentation. - - Sometimes it is convenient to indent the variables to make the code - look pretier, but do not add gratuitous space, try to use the minimally - necessary space, for example: - - Good: - - void Method () - { - string b; - int a; - byte c; - } - - Bad: - - void Method () - { - string b; - int a; - byte c; - } - - * Braces and the `else' clause - - If there are braces closing or opening next to the else clause, - they go on the same line as the word `else', for example: - - Good: - - if (..) { - - } else { - - } - - Bad: - - if (..) { - - } - else { - - } - - Bad: - - if (..) { - - } else - { - } - - Bad: - - if (..) { - - } - else - { - - } - -* RCS and CVS tags - - Some users like to use the special RCS/CVS tags in their - source code: $id$, $log$ and so on. - - The use of these is not permitted on the Mono source code - repository. This metadata belongs on a ChangeLog or in the - SVN metadata. - -* File formats - - Historically our repository has used a mix of line-endings, - this is a mistake that we are trying hard to fix. - - For existing files, please make sure that you do not convert - the file, as that causes us to loose precious history (the - full file is commited). - - For new files that you create, please make sure that you use - Subversion's support for mapping the line endings - automatically, after adding your file: - - $ svn add file.cs - - Execute this command: - - $ svn propset svn:eol-style native file.cs - - Which will make the file automatically receive the proper - treatment from that point on. - - Please verify before commiting that your changes wont loose - history, you can do this by running: - - $ svn diff - - And examining the output. - -* ChangeLogs - - ChangeLogs are the files that we use to track the project - history. ChangeLogs are found one per directory, or in small - projects, one per project. - - The format looks like this: - - 2004-11-19 Raja R Harinath - - * Makefile (%-profiles): Go through an intermediate - set of rules. Move body to ... - (profiles-do--%): ... this. - (profiles-do--run-test): Customized rule that usefully - runs with 'make -j' and 'make -k'. - (profiles-do--all, profile-do--%--all): Orchestrate - the bootstrap process. - - * file.cs (MainForm): Updated version. - - The date, author, email address in the first line. - - From that point on a list of changes in a file-by-file basis, - describing what changes were done. - - This information must be cut and pasted into your commit - message, so the information ends up in two places: in the - subversion repository metadata and also on the source code - distirbution (which does not have the Subversion metadata). - -* Warnings - - Avoid commiting code with warnings to the repository, the use - of #pragmas to disable warnings is strongly discouraged, but - can be used on unique cases. Please justify the use of the - warning ignore clause on a comment. - - Do not commit changes to the Makefiles that removes warnings, - if anything warnings should be eliminated one at a time, and - if not possible, they must be flagged. - - -* Examples: - -class X : Y { - - bool Method (int argument_1, int argument_2) - { - if (argument_1 == argument_2) - throw new Exception (Locale.GetText ("They are equal!"); - - if (argument_1 < argument_2) { - if (argument_1 * 3 > 4) - return true; - else - return false; - } - - // - // This sample helps keep your sanity while using 8-spaces for tabs - // - VeryLongIdentifierWhichTakesManyArguments ( - Argument1, Argument2, Argument3, - NestedCallHere ( - MoreNested)); - } - - bool MyProperty { - get { - return x; - } - - set { - x = value; - } - } - - void AnotherMethod () - { - if ((a + 5) != 4) { - } - - while (blah) { - if (a) - continue; - b++; - } - } -} - -* Conditional compilation - - Ideally we would not need conditional compilation, and the use - of #ifdef is strongly discouraged. But due to our support for - old C# 1.0 compilers we have to use it in a few places. - - Try to avoid negative tests that have an else clause, for - example: - - #if !NET_2_0 - CODE_FOR_1_0 - #else - CODE_FOR_2_0 - #endif - - Instead use: - - #if NET_2_0 - CODE_FOR_2_0 - #else - CODE_FOR_1_0 - #endif - - When a major feature differs across compilation targets, try - to factor out the code into a separate class, a helper class - or a separate file, and include that in your profile while - surrounding that helper file/class with the ifdefs to reduce - the amount of ifdefs in the code. - - For instance, this is used for some parts of Grasshopper where - the code is ifdefed out, when large parts of a file would have - been ifdefed out, we moved the code into a MyOtherFile.jvm.cs - - For 2.0 classes, this is even simpler as code can be trivially - factored out into - - MyHelperClass.cli.cs - MyHelperClass.jvm.cs - - By using partial classes. \ No newline at end of file +Please see http://www.mono-project.com/community/contributing/coding-guidelines/ for latest guidelines.