Table of Contents

Concept Reference

Cuemon for .NET was born out of simple idea; follow the design guidelines in the book Framework Design Guidelines by Krzysztof Cwalina and Brad Abrams while staying true to always follow the namespace of Microsoft .NET Framework 2.0.

A lot of water has passed under the bridge since the first version of Cuemon .NET Framework Additions, which consisted of only four assemblies and was closed source from 2008 till 2015.

Fast forwarding till today, Cuemon for .NET has matured and grown to be a reference project for all coders, programmers, developers and the likes thereof; programmed with passion and love for .NET, C# and software architecture in general.

With that prelude, lets look at the concepts behind the work.

Rules of engagement

  • Follow Framework Design Guidelines and Engineering Guidelines from Microsoft
  • Make sure to increment code coverage from unit test regularly
  • Follow recommendations from code quality analyzers; justify when a rule is either false-positive or not relevant
  • Maintain release notes and keep them as part of the code under Properties (PackageReleaseNotes.txt)
  • Adhere to SOLID principles for all new features
  • Do not let code rot; always embrace the boy scout rule
  • Make sure refactoring is done only on unit tested code (if no unit test - write unit test)
  • Extension methods in non-extension assemblies must be hidden by the IDecorator interface
  • Do not duplicate code

Solution Structure

The solution file is placed in the root of the Git repo.

Any supporting file for the solution (such as versioning, documentation, pipeline) is allowed to be placed in the root of the Git repo.
However, if and when supporting files start to clutter the solution, group them in context specific folders such as /.azure, /.github, /.nuget and the likes hereof.

Any build properties shared between projects must be placed in Directory.Build.props.
Any special build handling of projects must be placed in Directory.Build.targets.

All projects that is candidate for a NuGet package is placed in src.
All projects that is not candidate for a NuGet package is placed in tooling.
All unit test projects is placed in test and must follow these rules (as stated by Microsoft Engineering Guidelines):

  • The unit tests for the Cuemon.Foo assembly live in the Cuemon.Foo.Tests assembly
  • The functional tests for the Cuemon.Foo assembly live in the Cuemon.Foo.FunctionalTests assembly
  • Test class names end with Test and live in the same namespace as the class being tested, e.g., the unit tests for the Boo class that resides in the Cuemon.Foo assembly would be named BooTest and placed in the Cuemon.Foo namespace (hint: <RootNamespace>Cuemon.Foo</RootNamespace>) in the Cuemon.Foo.Tests assembly

Example of structure:

/src/Cuemon.Core/Security/HashFactory.cs
/src/Cuemon.Core/Cuemon.Core.csproj
/src/Cuemon.Core/Disposable.cs
/test/Cuemon.Core.Tests/Security/HashFactoryTest.cs
/test/Cuemon.Core.Tests/Cuemon.Core.Tests.csproj
/test/Cuemon.Core.Tests/DisposableTest.cs
/CHANGELOG.md
/Cuemon.sln
/Directory.Build.props
/Directory.Build.targets
/LICENSE.md
/README.md

The general naming pattern for projects is Cuemon.AspNetCore.<area>.<subarea>, Cuemon.<area>.<subarea>, and Cuemon.Extensions.<area>.<subarea>.
Cuemon.Extensions.<area>.<subarea> covers extension methods and/or new features that extends upon an existing project/package, such as Cuemon.Extensions.Net/Cuemon.Extensions.Xunit.

Principles

  • SOLID
    • Single Responsibility Principle (SRP)
    • Open-Closed Principle (OCP)
    • Liskov Substitution Principle (LSP)
    • Interface Segregation Principle (ISP)
    • Dependency Inversion Principle (DIP)
  • DRY
  • Consistency
  • Generality
  • Abstraction
  • Modularity
  • Separation of Concerns (SoC)
    • Same concept as two of the most important design principles of SOLID; SRP and ISP
  • Measure Twice, Cut Once

Patterns

  • Factory Method
  • Options / Parameter Object
  • Template Method
  • Decorator
  • Builder
  • Abstract Factory

Reusability

Extensions

Extensions, as in extension methods, is prohibited in all projects not following the Cuemon.Extensions.<area>.<subarea> convention.

That said, it is allowed to add extension methods that are not pure; eg. they have to be hidden by the IDecorator{T} interface.

Reason for this rule is, that developers are divided into two groups; those who embrace extension methods - and those who does not.

So by adhering to this rule, we ensure that both groups is taken care of; the former can consciously include Cuemon.Extensions.<area>.<subarea> and benefit from an abundant amount of extension methods, while the former can have peace of mind that no foreign extension methods is cluttering the IntelliSense.

Delegates

Tools

Continuous improvement of Cuemon for .NET

The constant of the code being written for Cuemon for .NET has and will always be Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries. In more recent history, Engineering Guidelines from Microsoft ASP.NET Core team, has also been widely adapted into this project.

Here is a non-exhausting list of literature and websites that inspires and keep this project going:

Books