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 it (eg. /.pipelines
folder).
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 unit test projects is placed in test
.
Example of structure:
/Cuemon.sln
/Directory.Build.props
/Directory.Build.targets
/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
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
- GitHub from Microsoft is used to host the source code of Cuemon for .NET
- Azure DevOps from Microsoft is used for CI/CD integration with GitHub
- Distributed packages are based on NuGet
- Preview packages are pushed to both GitHub (https://nuget.pkg.github.com/gimlichael/index.json) and a private feed (https://nuget.cuemon.net/v3/index.json)
- Stable and RCs are pushed to NuGet (https://api.nuget.org/v3/index.json)
- DocFx is used to produce documentation from source code including raw Markdown files
- Visual Studio 2019 from Microsoft is used as the primary tool for writing CSharp code
- ReSharper from JetBrains is an indispensable Visual Studio extension that makes development, refactoring and unit testing a bliss to work with
- GhostDoc Pro from SubMain Software is used to write all the source code documentation
- Visual Studio Code from Microsoft is used to anything besides writing CSharp code
- NuGet Package Explorer is helpful to iron out kinks of NuGet packages
- It goes without saying, that without Microsoft .NET there would be no Cuemon for .NET
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
- Framework Design Guidelines (1st. edition)
- Framework Design Guidelines (2nd. edition)
- Framework Design Guidelines (3rd. edition)
- Clean Code: A Handbook of Agile Software Craftsmanship
- Clean Architecture: A Craftsman's Guide to Software Structure and Design
- Building Maintainable Software, C# Edition: Ten Guidelines for Future-Proof Code
- Agile Principles, Patterns, and Practices in C#
- CLR via C#
- Microsoft .NET - Architecting Applications for the Enterprise