X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=mcs%2FCodingStyle;h=aa78389f7b7d05d136764df67ef9e87fbc554fc5;hb=22a47a566a02327b0ac815d3147d705c760defa7;hp=fbb7a68a101acb589ddfb362bfc05c1c2d133490;hpb=699e59742843044f6efa1726b7cb64f19d909e64;p=mono.git diff --git a/mcs/CodingStyle b/mcs/CodingStyle index fbb7a68a101..aa78389f7b7 100644 --- a/mcs/CodingStyle +++ b/mcs/CodingStyle @@ -1,17 +1,23 @@ -The class libraries are grouped together in the assemblies they belong. +* Coding Style for the Mono C# source code. -Each directory here represents an assembly, and inside each directory we -divide the code based on the namespace they implement. +* Class Libraries and Assembly Layout -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. + 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 @@ -19,12 +25,16 @@ testing. please use the attribute [MonoTODO]. This attribute can be used to programatically generate our status web pages: - [MonoTODO] + [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 @@ -93,7 +103,16 @@ testing. do_more (); } - A few guidelines: +* 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: @@ -262,8 +281,152 @@ testing. "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). - Here are a couple of examples: +* 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 { @@ -310,4 +473,44 @@ class X : Y { } } } - + +* 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