mirror of
https://github.com/BepInEx/mono.git
synced 2026-11-17 01:41:17 -10:00
507 lines
11 KiB
Plaintext
507 lines
11 KiB
Plaintext
* 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 ([email protected])
|
|
//
|
|
// (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 <[email protected]>
|
|
|
|
* 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. |