Flax contribution guidelines

manual/contributing/code-guidelines.md

@@ -0,0 +1,172 @@
+# Contribution Guidelines
+
+First of all, thanks for taking the time to read these guidelines on how to write code that adheres to the Flax code standards.
+
+> [!Note]
+> These guidelines are not absolute. Please use your best judgment; if a suggestion feels counterproductive or ill-suited to the specific context of the code you are writing, feel free to deviate from it. 
+>
+
+> [!Note]
+> Some parts of the codebase might break from these guidelines, mostly because they have been existing before this was written or because the note above. Feel free to correct those parts or open an issue on GitHub.
+>
+
+## General
+
+In general, you should make sure that all code that you contribute to Flax Engine is clean, readable and, if needed, sufficiently commented.
+
+## Opening a PR
+
+If your PR is just a few lines of code changed or a *really* obvious change, there is no need to describe what your PR does. However, the bigger in scope the PR is, the more you should make an effort to explain "What?" and "Why?" (something) was changed.
+
+Ask yourself what information potential reviewers or the person who will merge it might need. Include that in the description of your pull request.
+
+If you are in doubt wether a specific part of information is necessary, you should probably include it.
+
+### Common PR Review "pitfalls"
+- Cache `FlaxEngine.GUI.Style` in a variable ("`style`") when you are using it multiple times.
+
+## Codestyle
+
+> [!Note]
+> Some of this might overlap with the [Common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions).
+>
+
+- TODO: When `_variableName` vs when without `_`?
+- Don't use file scoped namespaces
+- Place a whitespace between a member, a math symbol and a value. Like for this example: `foo = 1f;`.
+
+### Use of Curly Braces
+
+- Don't use curly braces (`{}`) in a loop or a if statement body if the body line count does allow that (not more than one line). However, use them in an `else` or `else if` statement, no matter the line count.
+
+# [C#](#tab/code-csharp-curly-braces)
+```cs
+// No need to use curly braces.
+if (myBoolean)
+    Foo();
+
+// Use curly braces here, even if they could be left out for the else if statement.
+if (myOtherBoolean)
+{
+    float myFloat = Bar();
+    Foo(myFloat);
+}
+else if (myInt == 0)
+{
+    Foo(11f);
+}
+```
+***
+<br>
+
+- Don't use `{}` for your loops or if statements if the body of the statement is just one line. If you already are inside two `{}`, always use `{}`, no matter the body's line count. 
+
+### Cases
+
+- Use `PascalCase` for public fields and properties as well as method names.
+- Use `camelCase` for everything else.
+- Use `PascalCase` for constants (`const`) if you are defining it in class scope, use `camelCase` if it's defined in the scope of a method.
+
+### Declaration Order
+
+- Constants, fields and properties should be declared in this order:
+    1. `protected`
+    1. `private`
+    1. `public`
+- Methods should be declared in this order:
+    1. Constructors
+    1. `protected`
+    1. `private`
+    1. `public`
+- Constants should be declared first, before all other fields or properties.
+- `readonly` fields and properties should be declared first in their respective area
+- Properties should be declared after fields in their respective area
+- `Action`s should be declared last in their respective area
+- Leave a single empty line between variable declarations and the first method/ constructor (in C#).
+- If the class requires an empty constructor, it should always be placed on top of all other constructors. 
+
+## Comments
+
+- Use `// TODO: What is to be done?` or `// HACK: What is hacky?` to mark something that needs work/ to be done or a hack.
+- Check your comments for any grammar or spelling mistakes
+- Place a space in front of comment contents, like this `// Comment content.`
+
+### XML Documentation Comments
+
+> [!Tip]
+> Most IDEs will automatically create the framework for a documentation comment if you type three `/`.
+>
+
+- Use `/// <inheritdoc />` for overriden members that you want to inherit the documentation from their base implementation
+- Add a summary to all public or protected members, like this:
+
+# [C#](#tab/code-csharp-field-xml-summary)
+```cs
+/// <summary>
+/// Summary of the member.
+/// </summary>
+public float Foo;
+```
+***
+<br>
+
+# [C#](#tab/code-csharp-method-xml-summary)
+```cs
+/// <summary>
+/// Summary of the method.
+/// </summary>
+/// <param name="foo">Short summary of the `foo` parameter.</param>
+/// <returns>Short summary of what the method returns.</returns>
+public string Bar(float foo)
+{
+    // Method implementation...
+}
+```
+***
+<br>
+
+- When referring to another class, use the `see` keyword. When referring to another method parameter, use the `paramref` keyword. For example:
+
+# [C#](#tab/code-csharp-method-xml-summary)
+```cs
+/// <summary>
+/// Summary of the method.
+/// </summary>
+/// <param name="bar">A float.</param>
+/// <param name="baz">A <see cref="Color"/> (has some relationship with <paramref name="bar"/>)</param>
+public void Foo(float bar, Color baz)
+{
+    // Method implementation...
+}
+```
+***
+<br>
+
+## Deprecation of API
+
+It can happen that as part of your contribution you want to mark a part of the API as **deprecated**.
+
+For doing that, use the `[Obsolete]` attribute in C# and the `DEPRECATED()` macro in C++, like in these examples:
+
+# [C#](#tab/code-csharp)
+```cs
+/// <summary>
+/// Summary goes here.
+/// [Deprecated in v1.9]
+/// </summary>
+[Obsolete("Helpful deprecation message.")]
+public void Foo();
+```
+# [C++](#tab/code-cpp)
+```cpp
+/// <summary>
+/// Summary goes here.
+/// [Deprecated in v1.9]
+/// </summary>
+DEPRECATED("Helpful deprecation message.") void Foo() const;
+```
+***
+
+For marking part of an asset as deprecated, use the `MARK_CONTENT_DEPRECATED()` macro in C++ or `ContentDeprecated.Mark();` in C#.
+
+Deprecated API **should remain in the engine for ~2 years after the release** of the version that the API got deprecated in. 

manual/contributing/index.md

@@ -28,6 +28,8 @@ The repository available on GitHub is a mirror of our internal Git repository ho
 
 If you want to open the Flax Engine in Visual Studio you might need to install the [Flax Engine Tools for Visual Studio](https://marketplace.visualstudio.com/items?itemName=Flax.FlaxVS) extension (Not needed for Version 1.6 and higher).
 
+You can see guidelines on how to write code for Flax Engine [here](code-guidelines.md).
+
 ### Flax Docs
 
 The documentation you're reading right now is hosted as an open project on GitHub [here](https://github.com/FlaxEngine/FlaxDocs). You can fork the repository and edit it to contribute to the project or report issues there.