| title | description | published | date | tags | editor | dateCreated |
|---|---|---|---|---|---|---|
Contribution Guidelines |
Helping you helps us help you help us all |
true |
2021-09-11 05:25:10 UTC |
markdown |
2021-09-04 21:19:26 UTC |
These guidelines assume you are familiar with Markdown and Wiki.js. You are urged to familiarize yourself with the mentioned systems before you continue. {.is-warning}
The guidelines are a work-in-progress and might be changed if a situation requires it. Make sure to check these frequently - no effort will be made to notify you when the modifications to this pages are made. {.is-warning}
Only trusted people can edit and publish changes to this Wiki. Everyone else has read-only access. Feel free to contact me on telegram if you are interested in contributing to this documentation effort.
Level 2 header
A header defined by markdown as ##.
Level 3 header
A header defined by markdown as ###.
Level 4 and 5 headers
Headers defined by markdown as #### and #####, respectively. These are the only headers not visible in the table of contents for the page, so they should be used sparingly in order to avoid the user accidentally missing the documentation content.
It is recommended to use the Markdown editor when presented with the choice on the page configuration screen. Failure to do so might - and most likely will - result in your page being converted to conform with this recommendation.
Before creating a page, think about a good, meaningful title for it and - if a category isn't present already - how to categorize it correctly. Find a minimal set of words that accurately describes your feature. For example, if you wish to describe loading and playing sounds and music, the relevant title would be Playback located in the Audio category; if you wish to describe how to create a custom content provider, the relevant title would be Custom Content Provider located in the Content category; and so on.
A basic feature documentation page needs to contain sections in the order described below. This structure can be altered as needed if the feature described requires it.
This is a place where you would link the relevant API reference namespaces, so the user knows where to look for more information.
Requires level 2 header. A short introductory paragraph explaining what is the purpose of the feature and anything else that might be relevant to the user before they can start working with it.
Requires level 3 header. This is a section where you would put the using directives required to make the feature "visible" to the user's translation unit.
Requires level 2 header. This is a section where you would put practical examples of the user's feature. An example section needs to make the assumptions clear to the user before they get to the actual source code. This helps avoid situations like I copied the code but it does not work! Help!, which is all too familiar with sources copied from anywhere on the Internet. The sources should be packed into code blocks with CSharp code highlighter. For example:
```CSharp
// Your example goes here.
```
If you are referring to a type used in Chroma in your page, make sure to include link it to the API reference.
In order to document unexpected behavior, you are required to use a blockquote with {.is-warning} style clause. For example:
>Crabs have dangerous claws and it is foolish to put your fingers near these if the crab in question is alive.
{.is-warning}
There are a few other style clauses available. These are:
-
{.is-success}Use it to describe a recommended practice while using the documented feature. -
{.is-error}Used it to describe a warning which failure to take note of might lead to hard-to-debug issues or straight out framework crashes. -
{.is-info}Use it to describe facts about features that make the user's life easier, but don't qualify as any of the above.
Anyone can clone, modify the clone, and then send a pull request to the upstream repository. If your modifications fail to meet the following guidelines, the core development team will point out what is wrong and might ask you to (re-)visit this page, so it's worth to pay attention to this section.
4 spaces. Tabs are forbidden.
Chroma is a monolithic system at its heart. This means every core module goes into the Chroma sub-project. Chroma.Natives is a dependency that's bootstrapped when Chroma first loads into memory. Chroma.STB contains C# ports of the popular stb single-header C library collection.
A class, struct, enum, record or an interface should each have its own file. There is one exception to this rule and it only applies to private enumerations. This is explained in detail in the Nested enumerations section.
The top of a class consists of and follows the logical order of the following list:
- Constants
- Fields
- Delegates
- Indexers
- Properties
- Events
These should be ordered from the least accessible on top to the most accessible on bottom. See Window class for a good example of this rule.
The middle of a class consists solely of constructors. They are ordered from the least accessible on top, to the most accessible on bottom of the section.
The bottom of a class consists exclusively of methods, Contrary to the previous sections, methods are ordered from the most accessible on top, to the least accessible on bottom. Instance methods take precendence over static methods. Directly accessible methods take precedence over operators. See Color class implementation for details.
Ideally do not nest classes. If absolutely necessary, they must be private and go at the absolute bottom of the parent class.
Same as above, but if absolutely need and defined inside a class, they must be private and go above field declarations.
Constants must use PascalCase regardless of their accessibility level.
DO_NOT_YELL_IN_THE_CONSTANT_NAMES {.is-danger}
Do not define public fields unless absolutely necessary. Fields are considered implementation details. If you need your class to expose data, use properties instead. {.is-danger}
Private and protected fields must use lowerCamelCase and must have a single underscore _ prepended to their names.
private string _myString;
protected int _myProtectedInt;Internal, protected internal and public fields must use PascalCase.
internal string MyString;
protected internal string MyInternalProtectedString;
// Bad. Don't do it. I will yell at you.
// ~ vddcore
public int MyPublicField;All properties must use PascalCase regardless of their accessibility.
private int MyIntProperty { get; set; }
internal string MyStringProperty { get; set; }
public bool MyBoolProperty => false;All delegates must use PascalCase regardless of their accessibility and must have Delegate postfix appended.
private delegate void DoStuffNoReturnDelegate(string aParam, bParam);
protected delegate int DoStuffIntDelegate(bool someParameter);
public delegate bool CheckStuffDelegate();All constructors and methods must use PascalCase regardless of their accessibility. Single-statement methods should be expression-bodied.
public void DoStuff()
=> SingleStatement();
internal void DoStuffInternal()
{
// ...
}
internal protected void DoStuffNobodyElseDoes()
{
// ...
}
protected void ProcessThings(IEnumerable<string> things)
{
// ...
}
private void PrivatelyDoStuff()
{
// ...
}All method parameters must use lowerCamelCase.
All local method variables must use lowerCamelCase. Prefer var over explicit type declaration if your type doesn't break default expectations. Default expectation and violation of it is described with the following example:
var num = 0;
// Usually we use ints to store numbers when using C# and you kinda don't think about it twice when you see it.
// Don't do this.
var badByte = (byte)0;
// Prefer this instead.
byte goodByte = 0;