Merge branch 'master' into remove-glossary

Author: Ruben Schmidmeister

documentation/src/basic-constructs.md

@@ -7,9 +7,12 @@ Multiple expressions or statements in one line increase the mental burden while
 ## Prefer logical operators to if statements
 
 ```csharp
-if (node.GetParenthesis(key)) {
+if (node.GetParenthesis(key))
+{
     item.Setting = false;
-} else {
+}
+else
+{
     item.Setting = true;
 }
 ```
@@ -29,24 +32,28 @@ The condition of the if-statement should have no side effects.
 Avoid nested if-statements and prefer logical operators.
 
 ```csharp
-if (!Move(id)) {
+if (!Move(id))
+{
     return false;
 }
 
-if (!UpdateStart(StartValue)) {
+if (!UpdateStart(StartValue))
+{
     return false;
 }
 ```
 *Avoid side-effects*
 
 ```csharp
 var itemFound = Move(id);
-if (!itemFound) {
+if (!itemFound)
+{
     return false;
 }
 
 var updateIsReady = UpdateStart(StateDelete);
-if (!updateIsReady) {
+if (!updateIsReady)
+{
     return false;
 }
 ```
@@ -101,7 +108,8 @@ Avoid for-loops and use LINQ and higher order functions as an alternative.
 Whenever you are iterating over some kind of enumerator, prefer the foreach syntax:
 
 ```csharp
-foreach (var value in values.OrderByDescending(v => v)) {
+foreach (var value in values.OrderByDescending(v => v))
+{
     // Do something in reverse order
 }
 ```

documentation/src/comments.md

@@ -23,10 +23,12 @@ Try to document your public interface.
 
 ```csharp
 /// <summary>
-/// Disconnects a previously connected slot
+/// Specifies that <see cref="Open"/> should open an existing file.
+/// When the file is opened, it should be truncated so that its size is zero bytes.
+/// Requires that <see cref="Write"/> is called too.
+/// Can not be used to together with <see cref="Append"/>.
 /// </summary>
-/// <param name="slotId">id of the slot</param>
-void Disconnect(int slotId); 
+IFileOpeningBuilder Truncate(bool truncate = true);
 ```
 *Commenting a function*
 

documentation/src/naming.md

@@ -28,10 +28,18 @@ We do not use abbreviations that are ambiguous or unfamiliar to readers outside
 All abbreviations are written in PascalCase.
 
 ```csharp
-class JsonToHtmlConverter {}
-class IpAddress {}
-class UserId {}
-class TfsConnector {}
+class JsonToHtmlConverter
+{
+}
+class IpAddress
+{
+}
+class UserId
+{
+}
+class TfsConnector
+{
+}
 ```
 *Abbrevation Examples*
 
@@ -80,7 +88,8 @@ Table following table gives you the rules for each identifier.
 When dealing with UI Elements like buttons, combo boxes, grids, text boxes, etc. we append the full name of the type without any prefix to the variable name. 
 
 ```csharp
-class UserRightDialog {
+class UserRightDialog
+{
     Grid _userGrid;
     Edit _userNameEdit;
     Button _okButton;

documentation/src/oop.md

@@ -15,7 +15,7 @@ If the library you are using do not offer their own abstractions, create a facad
 Avoid the usage of new, either inject types through the constructor or use factories to create objects on runtime. All Factories should be declared via a delegate in the form of:
 
 ```csharp
-public delegate ReturnValue ReturnValueFactory(Parameters parameters)
+public delegate ReturnValue ReturnValueFactory(Parameters parameters);
 ```
 *Signature of factories*
 

documentation/src/types.md

@@ -5,10 +5,18 @@
 C# has a strong typing system, take advantage of it. A strong type will help you a lot in refactoring, and the compiler will easily tell you that you are using the wrong parameter if you do not have a string type like a comma separated list instead of a strong collection like a vector of longs.
 
 ```csharp
-class Vector {
-    int X;
-    int Y;
-    int Z;
+public sealed class Vector
+{
+    public Vector(int x, int y, int z)
+    {
+        X = x;
+        Y = y;
+        Z = z;
+    }
+
+    public int X { get; }
+    public int Y { get; }
+    public int Z { get; }
 }
 
 Vector CrossProduct(Vector factor1, Vector factor2);
@@ -25,21 +33,22 @@ The idea behind the new type idiom is to have additional type information, even
 So even if you have a single integer, you can create a new type from your abstract concept.
 
 ```csharp
-class Years {
-    Years(int years)
+public sealed class Years
+{
+    public Years(int years)
     {
         Value = years;
     }
 
-    int Value { get; }
+    public int Value { get; }
 }
 ```
 *Declaring the new type Years*
 
 In this case we have a time period in years. The constructor should be explicit, otherwise a Year object would be automatically constructed from a given integer. That way you need to be explicit when you call a function like this:
 
 ```csharp
-bool OldEnough(Years years)
+bool OldEnough(Years years);
 ```
 *Use the new type*