Update C# Coding Guidelines to v14

_config.yml

@@ -16,10 +16,10 @@ minimal_mistakes_skin    : "default" # "air", "aqua", "contrast", "dark", "dirt"
 
 # Site Settings
 locale                   : "en-US"
-title                    : "C# Coding Guidelines for all versions up to and including v10"
+title                    : "C# Coding Guidelines for all versions up to and including v14"
 title_separator          : "-"
 name                     : "Dennis Doomen"
-description              : "C# Coding Guidelines for all versions up to and including v10"
+description              : "C# Coding Guidelines for all versions up to and including v14"
 url                      : "https://csharpcodingguidelines.com/" # the base hostname & protocol for your site e.g. "https://mmistakes.github.io"
 baseurl                  : # the subpath of your site, e.g. "/blog"
 repository               : "dennisdoomen/csharpguidelines" # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes"

_data/navigation.yml

@@ -24,6 +24,8 @@ sidebar:
 
   - title: Guidelines
     children:
+      - title: General (AV0100)
+        url: /general-guidelines/
       - title: Class Design (AV1000)
         url: /class-design-guidelines/
       - title: Member Design (AV1100)
@@ -32,6 +34,8 @@ sidebar:
         url: /misc-design-guidelines/
       - title: Maintainability (AV1500)
         url: /maintainability-guidelines/
+      - title: Testability (AV1600)
+        url: /testability-guidelines/
       - title: Naming (AV1700)
         url: /naming-guidelines/
       - title: Performance (AV1800)

_includes/0001_Introduction.md

@@ -1,28 +1,25 @@
 ## 1.1. What is this?
 
-This document attempts to provide guidelines (or coding standards if you like) for all versions of C# up to and including v10 that are both valuable and pragmatic. Of course, if you create such a document you should practice what you preach. So rest assured, these guidelines are representative to what we at [Aviva Solutions](https://www.avivasolutions.nl) do in our day-to-day work. Notice that not all guidelines have a clear rationale. Some of them are simply choices we made at Aviva Solutions. In the end, it doesn't matter what choice you made, as long as you make one and apply it consistently.
+This document attempts to provide guidelines (or coding standards if you like) for all versions of C# up to and including v14 that are both valuable and pragmatic. Of course, if you create such a document you should practice what you preach. So rest assured, these guidelines are representative to what we at [Aviva Solutions](https://www.avivasolutions.nl) do in our day-to-day work. Notice that not all guidelines have a clear rationale. Some of them are simply choices we made at Aviva Solutions. In the end, it doesn't matter what choice you made, as long as you make one and apply it consistently.
+
+These guidelines are also used by all of Dennis Doomen's open-source projects, including [Fluent Assertions](https://fluentassertions.com/), [Liquid Projections](https://github.com/liquidprojections) and the [.NET Starter Kit](https://github.com/dennisdoomen/dotnet-starter-kit). The .NET Starter Kit in particular is a great companion project to see these guidelines in action.
 
 ## 1.2. Why would you use this document?
 
 Although some might see coding guidelines as undesired overhead or something that limits creativity, this approach has already proven its value for many years. This is because not every developer:
 
 - is aware that code is generally read 10 times more than it is changed;
 - is aware of the potential pitfalls of certain constructs in C#;
-- is up to speed on certain conventions when using the .NET Framework such as `IDisposable`, `async`/`await`, or the deferred execution nature of LINQ;
+- is up to speed on certain conventions when using .NET such as `IDisposable`, `async`/`await`, or the deferred execution nature of LINQ;
 - is aware of the impact of using (or neglecting to use) particular solutions on aspects like security, performance, multi-language support, etc;
 - realizes that not every developer is as capable, skilled or experienced to understand elegant, but potentially very abstract solutions;
 
 ## 1.3. Basic principles
 
 There are many unexpected things I run into during my work as a consultant, each deserving at least one guideline. Unfortunately, I still need to keep this document within a reasonable size. But unlike what some junior developers believe, that doesn't mean that something is okay just because it is not mentioned in this document.
 
-In general, if I have a discussion with a colleague about a smell that this document does not cover, I'll refer back to a set of basic principles that apply to all situations, regardless of context. These include:
+In general, if I have a discussion with a colleague about a smell that this document does not cover, I'll refer back to the [General Guidelines](/general-guidelines/) that apply to all situations, regardless of context. The only remaining exception is:
 
-- The Principle of Least Surprise (or Astonishment): you should choose a solution that everyone can understand, and that keeps them on the right track.
-- Keep It Simple Stupid (a.k.a. KISS): the simplest solution is more than sufficient.
-- You Ain't Gonna Need It (a.k.a. YAGNI): create a solution for the problem at hand, not for the ones you think may happen later on. Can you predict the future?
-- Don't Repeat Yourself (a.k.a. DRY): avoid duplication within a component, a source control repository or  a [bounded context](http://martinfowler.com/bliki/BoundedContext.html), without forgetting the [Rule of Three](http://lostechies.com/derickbailey/2012/10/31/abstraction-the-rule-of-three/) heuristic.
-- The [four principles of object-oriented programming](https://github.com/TelerikAcademy/Object-Oriented-Programming/tree/master/Topics/04.%20OOP-Principles-Part-1): encapsulation, abstraction, inheritance and polymorphism.
 - In general, generated code should not need to comply with coding guidelines. However, if it is possible to modify the templates used for generation, try to make them generate code that complies as much as possible.
 
 Regardless of the elegance of someone's solution, if it's too complex for the ordinary developer, exposes unusual behavior, or tries to solve many possible future issues, it is very likely the wrong solution and needs redesign. The worst response a developer can give you to these principles is: "But it works?".
@@ -31,17 +28,19 @@ Regardless of the elegance of someone's solution, if it's too complex for the or
 
 - Ask all developers to carefully read this document at least once. This will give them a sense of the kind of guidelines the document contains.
 - Make sure there are always a few hard copies of the [Cheat Sheet](https://github.com/dennisdoomen/CSharpGuidelines/releases/latest) close at hand.
-- Include the most critical coding guidelines on your [Project Checklist](https://www.continuousimprover.com/2010/03/alm-practices-5-checklists.html) and verify the remainder as part of your [Peer Review](https://www.continuousimprover.com/2010/02/tfs-development-practices-part-2-peer.html).
+- Include the most critical coding guidelines on your [Pull Request template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) and verify the remainder as part of your [Peer Review](https://www.continuousimprover.com/2010/02/tfs-development-practices-part-2-peer.html).
 - Consider forking the [original sources](https://github.com/dennisdoomen/csharpguidelines) on [GitHub](https://github.com/) and create your own [internal](https://github.com/dennisdoomen/csharpguidelines/blob/master/LICENSE.md) version of the document.
-- Jetbrain's [ReSharper](http://www.jetbrains.com/resharper/) and their fully fledged Visual Studio replacement [Rider](https://www.jetbrains.com/rider/), has an intelligent code inspection engine that, with some configuration, already supports many aspects of the Coding Guidelines. It automatically highlights any code that does not match the rules for naming members (e.g. Pascal or Camel casing), detects dead code, and many other things. One click of the mouse button (or the corresponding keyboard shortcut) is usually enough to fix it.
-- ReSharper also has a File Structure window that displays an overview of the members of your class or interface, and allows you to easily rearrange them using a simple drag-and-drop action.
+- Jetbrain's [ReSharper](https://www.jetbrains.com/resharper/) and their fully fledged Visual Studio replacement [Rider](https://www.jetbrains.com/rider/), has an intelligent code inspection engine that, with some configuration, already supports many aspects of the Coding Guidelines. It automatically highlights any code that does not match the rules for naming members (e.g. Pascal or Camel casing), detects dead code, and many other things. One click of the mouse button (or the corresponding keyboard shortcut) is usually enough to fix it.
+- Both ReSharper and Rider have a File Structure window that displays an overview of the members of your class or interface, and allows you to easily rearrange them using a simple drag-and-drop action.
 - [CSharpGuidelinesAnalyzer](https://github.com/bkoelman/CSharpGuidelinesAnalyzer) verifies over 40 of our guidelines, while typing code in Visual Studio 2017-2022 and during CI builds. An updated Resharper settings file is included.
+- Many of these guidelines are also enforced by [Roslyn analyzers](https://learn.microsoft.com/en-us/visualstudio/code-quality/roslyn-analyzers-overview). You can configure them centrally in a `Directory.Build.props` file to apply them to all projects in your solution.
+- If you need to use newer C# language features in projects targeting older .NET versions, consider [PolySharp](https://github.com/Sergio0694/PolySharp). It provides polyfills for many modern C# features, allowing you to write modern C# even when targeting older runtimes.
 
 ## 1.5. Why did we create it?
 
-The idea started in 2002 when Vic Hartog (Philips Medical Systems) and I were assigned the task of writing up a [coding standard](http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf) for C# 1.0. Since then, I've regularly added, removed and changed rules based on experiences, feedback from the community and new tooling support offered by a continuous stream of new developments in the .NET ecosystem. Special thanks go to [Bart Koelman](https://github.com/bkoelman) for being a very active contributor over all those years.
+The idea started in 2002 when Vic Hartog (Philips Medical Systems) and I were assigned the task of writing up a coding standard for C# 1.0. Since then, I've regularly added, removed and changed rules based on experiences, feedback from the community and new tooling support offered by a continuous stream of new developments in the .NET ecosystem. Special thanks go to [Bart Koelman](https://github.com/bkoelman) for being a very active contributor over all those years.
 
-Additionally, after reading [Robert C. Martin](https://sites.google.com/site/unclebobconsultingllc/)'s book [Clean Code: A Handbook of Agile Software Craftsmanship](http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882), I became a big fan of his ideas and decided to include some of his smells and heuristics as guidelines. Notice though, that this document is in no way a replacement for his book. I sincerely recommend that you read his book to gain a solid understanding of the rationale behind his recommendations.
+Additionally, after reading [Robert C. Martin](https://cleancoder.com/)'s book [Clean Code: A Handbook of Agile Software Craftsmanship](http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882), I became a big fan of his ideas and decided to include some of his smells and heuristics as guidelines. Notice though, that this document is in no way a replacement for his book. I sincerely recommend that you read his book to gain a solid understanding of the rationale behind his recommendations.
 
 I've also decided to include some design guidelines in addition to simple coding guidelines. They are too important to ignore and have a big influence in reaching high quality code.
 
@@ -59,7 +58,7 @@ To help you in this decision, I've assigned a level of importance to each guidel
 
 ## 1.7. Feedback and disclaimer
 
-This document has been compiled using many contributions from community members, blog posts, on-line discussions and two decades of developing in C#. If you have questions, comments or suggestions, just let me know by sending me an email at [dennis.doomen@avivasolutions.nl](mailto:dennis.doomen@avivasolutions.nl), [creating an issue](https://github.com/dennisdoomen/csharpguidelines/issues) or Pull Request on GitHub, ping me at [http://twitter.com/ddoomen](http://twitter.com/ddoomen) or join the [Gitter discussions](https://gitter.im/dennisdoomen/CSharpGuidelines). I will try to revise and republish this document with new insights, experiences and remarks on a regular basis.
+This document has been compiled using many contributions from community members, blog posts, on-line discussions and two decades of developing in C#. If you have questions, comments or suggestions, just let me know by sending me an email at [dennis.doomen@avivasolutions.nl](mailto:dennis.doomen@avivasolutions.nl), [creating an issue](https://github.com/dennisdoomen/csharpguidelines/issues) or Pull Request on GitHub, or ping me at [https://bsky.app/profile/ddoomen.bsky.social](https://bsky.app/profile/ddoomen.bsky.social) or [https://mastodon.social/@ddoomen](https://mastodon.social/@ddoomen). I will try to revise and republish this document with new insights, experiences and remarks on a regular basis.
 
 Notice though that it merely reflects my view on proper C# code so Aviva Solutions will not be liable for any direct or indirect damages caused by applying the guidelines of this document. This document is published under a Creative Commons license, specifically the [Creative Commons Attribution-ShareAlike 4.0](http://creativecommons.org/licenses/by-sa/4.0/) license.
 

_pages/0000_CoverAndStyles.md

@@ -12,7 +12,7 @@ NOTE: Requires Markdown Extra. See http://michelf.ca/projects/php-markdown/extra
 Coding Guidelines
 </div><br/>
 <div class="subTitle">
-for all C# versions up to v10
+for all C# versions up to v14
 </div>
 <br/>
 <div class="author">

_pages/0100_GeneralGuidelines.md

@@ -0,0 +1,10 @@
+---
+title: General Guidelines
+permalink: /general-guidelines/
+classes: wide
+search: true
+sidebar:
+  nav: "sidebar"
+rule_category: general
+layout: rule-category
+---

_pages/1600_TestabilityGuidelines.md

@@ -0,0 +1,10 @@
+---
+title: Testability Guidelines
+permalink: /testability-guidelines/
+classes: wide
+search: true
+sidebar:
+  nav: "sidebar"
+rule_category: testability
+layout: rule-category
+---

_pages/9999_ResourcesAndLinks.md

@@ -9,7 +9,7 @@ sidebar:
 In addition to the many links provided throughout this document, I'd like to recommend the following books, articles and sites for everyone interested in software quality:
 
 * [Code Complete: A Practical Handbook of Software Construction](http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670) (Steve McConnel)
-One of the best books I've ever read. It deals with all aspects of software development, and even though the book was originally written in 2004 you'll be surprised when you see how accurate it still is. I wrote a [review](http://www.continuousimprover.com/2009/07/book-review-code-complete-2nd-edition.html) in 2009 if you want to get a sense of its contents.
+One of the best books I've ever read. It deals with all aspects of software development, and even though the book was originally written in 2004 you'll be surprised when you see how accurate it still is.
 
 * [The Art of Agile Development](http://www.amazon.com/Art-Agile-Development-James-Shore/dp/0596527675) (James Shore)
 Another great all-encompassing trip through the many practices preached by processes like Scrum and Extreme Programming. If you're looking for a quick introduction with a pragmatic touch, make sure you read James's book.
@@ -20,11 +20,8 @@ The book that started my interest for both Domain-Driven Design and Test-Driven
 * [Jeremy D. Miller's Blog](https://jeremydmiller.com/)
 Jeremy has written some excellent blog posts on Test-Driven Development, Design Patterns and design principles. I've learned a lot from his real-life and practical insights.
 
-* [LINQ Framework Design Guidelines](https://blogs.msdn.microsoft.com/mirceat/2008/03/12/linq-framework-design-guidelines/)
-A set of rules and recommendations that you should adhere to when creating your own implementations of `IQueryable`.
-
 * [Guidance on Asynchronous Programming](https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md) (David Fowler)
 Best practices for `async`/`await` with examples of bad and good patterns of how to write asynchronous code.
 
-* [Best Practices for c# async/await](https://msdn.microsoft.com/en-us/magazine/jj991977.aspx)
-Older (but still valid) overview of crucial practices to follow when adopting `async` and `await` in your own code base.
+* [Best Practices for C# async/await](https://learn.microsoft.com/en-us/archive/msdn-magazine/2013/march/async-await-best-practices-in-asynchronous-programming)
+Overview of crucial practices to follow when adopting `async` and `await` in your own code base.