godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2572 from Calinou/improve-csharp-style-guide

Browse Source 
Improve the C# style guide and mention C# 7.0 as minimum version
This commit is contained in:
Rémi Verschelde
2019-07-02 13:34:47 +02:00
committed by GitHub
parent f2137a4e84 7d86b8553f
commit 5a9024fdbc
1 changed files with 44 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
getting_started/scripting/c_sharp/c_sharp_style_guide.rst
View File

@@ -20,9 +20,9 @@ of the language, we encourage you to do the same, especially if you do not have
Language specification
----------------------
Currently, Godot uses C# version 6.0 in its engine and example source code. So, before we move to
a newer version, care must be taken to avoid mixing language features only available in C# 7.0 or
later, such as pattern matching or expression-bodied members inside get/set accessors.
Godot currently uses **C# version 7.0** in its engine and example source code. So, before we move to
a newer version, care must be taken to avoid mixing language features only available in C# 7.1 or
later.
For detailed information on C# features in different versions, please see
`What's New in C# <https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/>`_.
@@ -30,14 +30,15 @@ For detailed information on C# features in different versions, please see
Formatting conventions
----------------------
* If you create a new file, make sure that it uses linefeed (*LF*) characters to break lines, not *CRLF* or *CR*.
* Use UTF-8 encoding without a byte order mark (BOM <https://en.wikipedia.org/wiki/Byte_order_mark>).
* Use 4 spaces instead of tabs for indentation (which is referred to as 'soft tabs').
* Use line feed (**LF**) characters to break lines, not CRLF or CR.
* Use **UTF-8** encoding without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`_.
* Use **4 spaces** instead of tabs for indentation (which is referred to as "soft tabs").
* Consider breaking a line into several if it's longer than 100 characters.
Line breaks and blank lines
---------------------------
For a general indentation rule, follow `The 'Allman Style' <https://en.wikipedia.org/wiki/Indentation_style#Allman_style>`_
For a general indentation rule, follow `the "Allman Style" <https://en.wikipedia.org/wiki/Indentation_style#Allman_style>`_
which recommends placing the brace associated with a control statement on the next line, indented to
the same level:
@@ -82,7 +83,7 @@ However, you may choose to omit line breaks inside brackets:
Insert a blank line:
* After *using* statement list.
* After a list of ``using`` statements.
* Between method, properties, and inner type declarations.
* At the end of each file.
@@ -93,63 +94,59 @@ Avoid inserting a blank line:
* After ``{``, the opening brace.
* Before ``}``, the closing brace.
* After a comment block, or a single line comment.
* After a comment block or a single-line comment.
* Adjacent to another blank line.
.. code-block:: csharp
using System;
using Godot;
// Blank line after using list.
// Blank line after `using` list.
public class MyClass
{ // No blank line after '{'.
{ // No blank line after `{`.
public enum MyEnum
{
Value,
AnotherValue // No blank line before '}'.
AnotherValue // No blank line before `}`.
}
// Blank line around inner types.
// Blank line around inner types.
public const int SomeConstant = 1;
public const int AnotherConstant = 2;
private Vector3 _x;
private Vector3 _y; // Related constants or fields can be
// grouped together.
private Vector3 _x; // Related constants or fields can be
private Vector3 _y; // grouped together.
private float _width;
private float _height;
public int MyProperty { get; set; }
// Blank line around properties.
// Blank line around properties.
public void MyMethod()
{
// Some comment.
AnotherMethod(); // No blank line after a comment.
AnotherMethod(); // No blank line after a comment.
}
// Blank line around methods.
// Blank line around methods.
public void AnotherMethod()
{
}
}
Consider breaking a line when it's longer than 100 characters.
Ensure that all lines use the Unix LF format, not CRLF.
Using spaces
------------
Insert a space:
* Around a binary and tertiary operator.
* Between an opening parenthesis and *if*, *for*, *foreach*, *catch*, *while*, *lock* or *using* keywords.
* Between an opening parenthesis and ``if``, ``for``, ``foreach``, ``catch``, ``while``, ``lock`` or ``using`` keywords.
* Before and within a single line accessor block.
* Between accessors in a single line accessor block.
* After a comma.
* After a semi-colon in a *for* statement.
* After a colon in a single line *case* statement.
* After a semicolon in a ``for`` statement.
* After a colon in a single line ``case`` statement.
* Around a colon in a type declaration.
* Around a lambda arrow.
* After a single line comment symbol ('//'), and before it if used at the end of a line.
* After a single-line comment symbol (``//``), and before it if used at the end of a line.
Do not use a space:
@@ -193,7 +190,7 @@ The following example shows a proper use of spaces, according to some of the abo
Naming conventions
------------------
Use *PascalCase* for all namespaces, type names and member level identifiers (i.e. methods, properties,
Use **PascalCase** for all namespaces, type names and member level identifiers (i.e. methods, properties,
constants, events), except for private fields:
.. code-block:: csharp
@@ -214,12 +211,12 @@ constants, events), except for private fields:
}
}
Use *camelCase* for all other identifiers (i.e. local variables, method arguments), and use
underscore('_') as a prefix for private fields (but not for methods or properties, as explained above):
Use **camelCase** for all other identifiers (i.e. local variables, method arguments), and use
an underscore (``_``) as a prefix for private fields (but not for methods or properties, as explained above):
.. code-block:: csharp
private Vector3 _aimingAt; // Use '_' prefix for private fields.
private Vector3 _aimingAt; // Use a `_` prefix for private fields.
private void Attack(float attackStrength)
{
@@ -228,10 +225,10 @@ underscore('_') as a prefix for private fields (but not for methods or propertie
targetFound?.Hit(attackStrength);
}
There's an exception with acronyms which consist of two letters, like *'UI'*, which should be written in
uppercase letters when used where Pascal case would be expected, and in lowercase letters otherwise.
There's an exception with acronyms which consist of two letters, like ``UI``, which should be written in
uppercase letters where PascalCase would be expected, and in lowercase letters otherwise.
Note that *'id'* is **not** an acronym, so it should be treated as a normal identifier:
Note that ``id`` is **not** an acronym, so it should be treated as a normal identifier:
.. code-block:: csharp
@@ -242,20 +239,20 @@ Note that *'id'* is **not** an acronym, so it should be treated as a normal iden
get { return uiManager; }
}
It is generally discouraged to use a type name as a prefix of an identifier, like *'string strText'*
or *'float fPower'*, for example. An exception is made, however, for interfaces, which
**should**, in fact, have an uppercase letter *'I'* prefixed to their names, like *'IInventoryHolder'* or *'IDamageable'*.
It is generally discouraged to use a type name as a prefix of an identifier, like ``string strText``
or ``float fPower``, for example. An exception is made, however, for interfaces, which
**should**, in fact, have an uppercase letter ``I`` prefixed to their names, like ``IInventoryHolder`` or ``IDamageable``.
Lastly, consider choosing descriptive names and do not try to shorten them too much if it affects
readability.
For instance, if you want to write code to find a nearby enemy and hit it with a weapon, prefer
For instance, if you want to write code to find a nearby enemy and hit it with a weapon, prefer:
.. code-block:: csharp
FindNearbyEnemy()?.Damage(weaponDamage);
Rather than,
Rather than:
.. code-block:: csharp
@@ -264,7 +261,7 @@ Rather than,
Implicitly typed local variables
--------------------------------
Consider using implicitly typing (*'var'*) for declaration of a local variable, but do so
Consider using implicitly typing (``var``) for declaration of a local variable, but do so
**only when the type is evident** from the right side of the assignment:
.. code-block:: csharp
@@ -288,8 +285,8 @@ Consider using implicitly typing (*'var'*) for declaration of a local variable,
var velocity = direction * 1.5;
// It's generally a better idea to use explicit typing for numeric values, especially with
// the existence of 'real_t' alias in Godot, which can either be double or float depending
// on the build configuration.
// the existence of the `real_t` alias in Godot, which can either be double or float
// depending on the build configuration.
var value = 1.5;
@@ -298,9 +295,10 @@ Other considerations
* Use explicit access modifiers.
* Use properties instead of non-private fields.
* Use modifiers in this order: *'public/protected/private/internal virtual/override/abstract/new static readonly'*.
* Avoid using fully qualified names or *'this.'* prefix for members when it's not necessary.
* Remove unused *'using'* statements and unnecessary parentheses.
* Consider omitting default initial value for a type.
* Use modifiers in this order:
``public``/``protected``/``private``/``internal``/``virtual``/``override``/``abstract``/``new``/``static``/``readonly``.
* Avoid using fully-qualified names or ``this.`` prefix for members when it's not necessary.
* Remove unused ``using`` statements and unnecessary parentheses.
* Consider omitting the default initial value for a type.
* Consider using null-conditional operators or type initializers to make the code more compact.
* Use safe cast when there is a possibility of the value being a different type, and use direct cast otherwise.