Merge pull request #260 from pcc/topmost

[mono.git] / mcs / CodingStyle

* 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.

* 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  <rharinath@novell.com>

                * 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.