Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Removing old wiki references #5152

Merged
merged 4 commits into from Sep 3, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
228 changes: 228 additions & 0 deletions CODESTYLE.md
@@ -0,0 +1,228 @@
> #### NOTE: This code style standard for MonoGame is a work in progress and much of the code does not currently conform to these rules. This is something that will be addressed by the core team.

# Introduction
As the MonoGame project gains more traction and becomes more widely used, we are aiming to provide a more professional and consistent look to the large amount of source now in the project. It was a broadly supported decision by the core development team to follow the Microsoft coding guidelines (the default provided in Visual Studio's C# editor). These coding guidelines listed below have been based on a [MSDN blog post](http://blogs.msdn.com/b/brada/archive/2005/01/26/361363.aspx) from 2005 by Brad Abrams describing the internal coding guidelines at Microsoft, with some changes to suit our project.
# Coding Guidelines
## Tabs & Indenting
Tab characters (\0x09) should not be used in code. All indentation should be done with 4 space characters.
## Bracing
Open braces should always be at the beginning of the line after the statement that begins the block. Contents of the brace should be indented by 4 spaces. Single statements do not have braces. For example:
```
if (someExpression)
{
DoSomething();
DoAnotherThing();
}
else
DoSomethingElse();
```

`case` statements should be indented from the switch statement like this:
```
switch (someExpression)
{
case 0:
DoSomething();
break;

case 1:
DoSomethingElse();
break;

case 2:
{
int n = 1;
DoAnotherThing(n);
}
break;
}
```

Braces are not used for single statement blocks immediately following a `for`, `foreach`, `if`, `do`, etc. The single statement block should always be on the following line and indented by four spaces. This increases code readability and maintainability.
```
for (int i = 0; i < 100; ++i)
DoSomething(i);
```

## Single line property statements
Single line property statements can have braces that begin and end on the same line. This should only be used for simple property statements. Add a single space before and after the braces.
```
public class Foo
{
int bar;

public int Bar
{
get { return bar; }
set { bar = value; }
}
}
```

## Commenting
Comments should be used to describe intention, algorithmic overview, and/or logical flow. It would be ideal, if from reading the comments alone, someone other than the author could understand a function�s intended behavior and general operation. While there are no minimum comment requirements and certainly some very small routines need no commenting at all, it is hoped that most routines will have comments reflecting the programmer�s intent and approach.

Comments must provide added value or explanation to the code. Simply describing the code is not helpful or useful.
```
// Wrong
// Set count to 1
count = 1;

// Right
// Set the initial reference count so it isn't cleaned up next frame
count = 1;
```

### Copyright/License notice
Each file should start with a copyright notice. To avoid errors in doc comment builds, you don�t want to use triple-slash doc comments. This is a short statement declaring the project name, copyright notice and directing the reader to the license document elsewhere in the project.
```
// MonoGame - Copyright (C) The MonoGame Team
// This file is subject to the terms and conditions defined in
// file 'LICENSE.txt', which is part of this source code package.
```

### Documentation Comments
All methods should use XML doc comments. For internal dev comments, the `<devdoc>` tag should be used.
```
public class Foo
{
/// <summary>Public stuff about the method</summary>
/// <param name=�bar�>What a neat parameter!</param>
/// <devdoc>Cool internal stuff!</devdoc>
public void MyMethod(int bar)
{
}
}
```

### Comment Style
The // (two slashes) style of comment tags should be used in most situations. Where ever possible, place comments above the code instead of beside it. Here are some examples:
```
// This is required for WebClient to work through the proxy
GlobalProxySelection.Select = new WebProxy("http://itgproxy");

// Create object to access Internet resources
WebClient myClient = new WebClient();
```

## Spacing
Spaces improve readability by decreasing code density. Here are some guidelines for the use of space characters within code:

Do use a single space after a comma between function arguments.
```
Console.In.Read(myChar, 0, 1); // Right
Console.In.Read(myChar,0,1); // Wrong
```
Do not use a space after the parenthesis and function arguments
```
CreateFoo(myChar, 0, 1) // Right
CreateFoo( myChar, 0, 1 ) // Wrong
```
Do not use spaces between a function name and parenthesis.
```
CreateFoo() // Right
CreateFoo () // Wrong
```
Do not use spaces inside brackets.
```
x = dataArray[index]; // Right
x = dataArray[ index ]; // Wrong
```
Do use a single space before flow control statements
```
while (x == y) // Right
while(x==y) // Wrong
```
Do use a single space before and after binary operators
```
if (x == y) // Right
if (x==y) // Wrong
```
Do not use a space between a unary operator and the operand
```
++i; // Right
++ i; // Wrong
```
Do not use a space before a semi-colon. Do use a space after a semi-colon if there is more on the same line
```
for (int i = 0; i < 100; ++i) // Right
for (int i=0 ; i<100 ; ++i) // Wrong
```

## Naming
Follow all .NET Framework Design Guidelines for both internal and external members. Highlights of these include:
* Do not use Hungarian notation
* Do use an underscore prefix for member variables, e.g. `_foo`
* Do use camelCasing for member variables (first word all lowercase, subsequent words initial uppercase)
* Do use camelCasing for parameters
* Do use camelCasing for local variables
* Do use PascalCasing for function, property, event, and class names (all words initial uppercase)
* Do prefix interfaces names with �I�
* Do not prefix enums, classes, or delegates with any letter

The reasons to extend the public rules (no Hungarian, underscore prefix for member variables, etc.) is to produce a consistent source code appearance. In addition a goal is to have clean readable source. Code legibility should be a primary goal.

## File Organization
* Source files should contain only one public type, although multiple internal types are permitted if required
* Source files should be given the name of the public type in the file
* Directory names should follow the namespace for the class after `Framework`. For example, I would expect to find the public class `Microsoft.Xna.Framework.Graphics.GraphicsDevice` in **MonoGame.Framework\Graphics\GraphicsDevice.cs**
* Class members should be grouped logically, and encapsulated into regions (Fields, Constructors, Properties, Events, Methods, Private interface implementations, Nested types)
* Using statements should be before the namespace declaration.
```
using System;

namespace MyNamespace
{
public class MyClass : IFoo
{
#region Fields
int foo;
#endregion

#region Properties
public int Foo { get { � } set { � } }
#endregion

#region Constructors
public MyClass()
{
}
#endregion

#region Events
public event EventHandler FooChanged { add { � } remove { � } }
#endregion

#region Methods
void DoSomething()
{
}

void FindSomething()
{
}
#endregion

#region Private interface implementations
void IFoo.DoSomething()
{
DoSomething();
}
#endregion

#region Nested types
class NestedType
{
}
#endregion
}
}
```

# Useful Links
[C# Coding Conventions (MSDN)](http://msdn.microsoft.com/en-us/library/ff926074.aspx)
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Expand Up @@ -31,7 +31,7 @@ Here are a few simple rules and suggestions to remember when contributing to Mon
* **PLEASE** be sure to write simple and descriptive commit messages.
* **DO NOT** surprise us with new APIs or big new features. Open an issue to discuss your ideas first.
* **DO NOT** reorder type members as it makes it difficult to compare code changes in a PR.
* **DO** try to follow our [coding style](https://github.com/mono/MonoGame/wiki/Coding-Guidelines) for new code.
* **DO** try to follow our [coding style](CODESTYLE.md) for new code.
* **DO** give priority to the existing style of the file you're changing.
* **DO** try to add to our [unit tests](Test) when adding new features or fixing bugs.
* **DO NOT** send PRs for code style changes or make code changes just for the sake of style.
Expand Down
1 change: 0 additions & 1 deletion Documentation/tutorials.md
Expand Up @@ -35,7 +35,6 @@ Tara Walker's "Building a Shooter Game" tutorial series.
- [BMFont rendering with MonoGame](http://www.craftworkgames.com/blog/tutorial-bmfont-rendering-with-monogame/)
- [RB Whitaker's MonoGame Tutorials](http://rbwhitaker.wikidot.com/monogame-tutorials)
- [RB Whitaker's XNA Tutorials including sharers, 2D, 3D, Game loops, advancted topics](http://rbwhitaker.wikidot.com/xna-tutorials)
- [Another list of tutorials from the MonoGame github](https://github.com/mono/MonoGame/wiki/Tutorials)
- [Setting window position tutorial](http://projectdrake.net/blog/?p=176)
- [Using Spine with MonoGame - by Randolph Burt (Randeroo)](http://randolphburt.co.uk/2013/03/30/dragons-and-dancing-crabs/)
- [Mac porting series](http://benkane.wordpress.com/2012/01/20/the-great-porting-adventure-day-8/)
Expand Down
2 changes: 0 additions & 2 deletions Documentation/welcome.md
Expand Up @@ -3,8 +3,6 @@ Welcome to the MonoGame game library documentation hub.
### WORK IN PROGRESS
Note that the MonoGame documentation project is currently a work in progress and applies to the **latest development build** of MonoGame.

If you are looking for documentation on previous releases of MonoGame you can reference our [GitHub wiki](http://github.com/mono/MonoGame/wiki) and the original [Codeplex documentation](http://monogame.codeplex.com/documentation) while we're getting this all sorted out.

### We Need Your Help!
Truly great open source projects require high quality documentation. This is call for volunteers to help us make the MonoGame documentation truly great. If you can help write tutorials, guides, code snippets, reference docs, video walkthroughs or just any improvement to our current documentation we could use your help!

Expand Down