README.md

Belp.Formatting

An unofficial bundle of formatting tools to enforce writing C# in the most conventional manner possible.

The package deviates from Microsoft's established conventions in several areas. For example,

• _camelCase for private fields.
• PreEvent/PostEvent or BeforeEvent/AfterEvent instead of Eventing/Evented.

Furthermore, the opinion of this package on some disputed C# conventions are as follows,

• Explicit type over var unless evident.

  IEnumerable<string> x = GetNames();
  var y = (string)obj;
  var z = new object();
  object a = new();
  int b = 2;
  var c = 3L;

• All methods must use block bodies, as opposed to expression bodies. However, properties may use either block bodies or expression bodies.
• All selective statements(if, switch), loop statements(while, for), and other similar statements must be accompanied by curly braces. One notable exception is a series of using statements after another.

  // Permitted
  using (null)
  using (null)
  using (null)
  {
  }
  
  // Permitted
  using (null)
  {
      using (null)
      {
          using (null)
          {
          }
      }
  }

• No parentheses or grouping constructs unless necessary.
• Switch case contents must be wrapped in {} and must have the break statement placed outside the curly braces if possible.

Comment Legend

#§ Analyzers section
#¶ Analyzers subsection
#: Analyzer description
#> Link to documentation
#! Per-project configuration
#? Per-user configuration
#- Removed
#X Superseded by another analyzer
#/ Miscellaneous comment

Some common reasons for an analyzer to be disabled is as follows,

• Situational: the analyzer is sometimes useful and sometimes not.
• Subjective: the reported issue is decided by the opinions of the developer.
• Too broad: the analyzer reports too many false positives

Installation

Requirements

• .NET SDK 8 or newer

Install using an Editor

1. Locate the project file(for example, Project.csproj, Project.fsproj).
2. Open the project file in an editor.
3. Locate the an <ItemGroup>.
4. Add a new PackageReference element to the item group with the Include attribute set to Belp.Formatting and the Version attribute set to 0.0.1 or a version of choosing. For example, <PackageReference Include="Belp.Formatting" Version="0.0.1" />.
5. Run dotnet restore.

Uninstallation

1. Locate the project file(for example, Project.csproj, Project.fsproj).
2. Open the project file in an editor.
3. Locate the PackageReference element with an Include attribute set to Belp.Formatting.
4. Delete the element.

Install using the .NET CLI

1. Open a terminal.
2. Navigate to the containing directory of the project file.
3. Run the command dotnet add package Belp.Formatting.

Uninstallation

1. Open a terminal.
2. Navigate to the containing directory of the project file.
3. Run the command dotnet remove package Belp.Formatting.

Install using Visual Studio Package Manager

1. Open Visual Studio.
2. Right click the project in the Solution Explorer.
3. Click on "Manage NuGet Packages".
4. Go to the "Browse" tab.
5. Search for Belp.Formatting.
6. Install.

Uninstallation

1. Open Visual Studio.
2. Right click the project in the Solution Explorer.
3. Click on "Manage NuGet Packages".
4. Go to the "Installed" tab.
5. Click on Belp.Formatting.
6. Click on "Uninstall".

Usage

The package automatically configures the formatting upon installation.

Development

Prerequisites

• Install the .NET 8.0 SDK version 8.0.100 or newer.

Building with Visual Studio

1. Open Belp.Formatting.sln.
2. Open the Solution Explorer.
3. Right click on the project Belp.Formatting in the Solution Explorer.
4. Click on Pack.

Building with .NET CLI

1. Open a terminal in the repository root.
2. Run dotnet pack

Output

By default, the output is located in src/Belp.Formatting/Belp.Formatting/bin/Release/.