From 67e7a9137142235d6bf978b250bd88a69bf97284 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Fri, 18 Jul 2025 15:32:31 +0200 Subject: [PATCH 1/7] Update README Clarifies extension method restrictions for certain types --- README.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 463b50c..0c6b517 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,30 @@ This is a collection of utilities that we have created to help with our development process. We have decided to open source these utilities in the hopes that they will be useful to others. ## Usage -To use these utilities, simply add the Nuget package to your project and use the desired classes in your source code. + +Add the NuGet package to your project and reference the desired classes in your source code. ## Contributing + If you would like to contribute to this project, please submit a pull request. -### Guidelines +### Namespace Organization + +Use a namespace that reflects the utility's purpose. Choose names that are specific enough to be meaningful but generic enough to accommodate similar utilities in the future. + +### Extension Method Restrictions -- Use a namespace that fits what the utility is doing. If you introduce a new namespace, choose a name that fits your utility but is still generic enough to hold similar utilities that can be added later alongside your addition. -- Try to create your utility as an extension method. Except it would extend a primitive type like Boolean, Byte, SByte, Int16, UInt16, Int32, UInt32, Int64, UInt64, IntPtr, UIntPtr, Char, Double, or Single. -- Add tests to your utilities and strive to cover many different usage scenarios and parametrization and high code coverage. +To prevent API pollution and naming conflicts, use static helper classes instead of extension methods for the following types: + +- All CLR primitives (`bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `nint`, `nuint`, `char`, `double`, `float`) +- The following System .NET types: `string`, `decimal`, `object`, `Enum`, `DateTime`, `Guid`, and `TimeSpan`. + +### Test Coverage + +Add comprehensive unit tests that cover various usage scenarios, edge cases, and parameter combinations. Strive for high code coverage to ensure reliability. ## Releases + Due to the nature of this project as a loosely connected collection of utilities, it's important to be strict about following [SemVer](https://semver.org/) to communicate possible breaking changes to the users of this library via version number. Equally as important is to be precise about the changes made in each release and maintain the [CHANGELOG.md](CHANGELOG.md) according to the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format so users of this library can see easily where changes were made. From 11cb4a5ff171ee91b3573d581d1e3f6624ba62e1 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Mon, 21 Jul 2025 11:32:13 +0200 Subject: [PATCH 2/7] remove a few types after internal discussion --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0c6b517..d2bc77f 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Use a namespace that reflects the utility's purpose. Choose names that are speci To prevent API pollution and naming conflicts, use static helper classes instead of extension methods for the following types: - All CLR primitives (`bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `nint`, `nuint`, `char`, `double`, `float`) -- The following System .NET types: `string`, `decimal`, `object`, `Enum`, `DateTime`, `Guid`, and `TimeSpan`. +- Some System .NET types: `string`, `decimal`, `object` and `Enum`. ### Test Coverage From dec7d09bb56ded5f0e07889fbf076c8ed9c4c276 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Mon, 21 Jul 2025 14:40:12 +0200 Subject: [PATCH 3/7] Add an exception for using the `ToXyzString()` naming convention --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d2bc77f..f7c3cab 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,9 @@ Use a namespace that reflects the utility's purpose. Choose names that are speci To prevent API pollution and naming conflicts, use static helper classes instead of extension methods for the following types: - All CLR primitives (`bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `nint`, `nuint`, `char`, `double`, `float`) -- Some System .NET types: `string`, `decimal`, `object` and `Enum`. +- Selected System .NET types: `string`, `decimal`, `object`, and `Enum` + +**Exception:** Extension methods that provide custom string representations are permitted, provided they follow the `ToXyzString()` naming convention, where `Xyz` clearly indicates the format or purpose of the output (e.g., `ToCurrencyString()`, `ToHexString()`). This ensures consistency and clarity in API design across the library. ### Test Coverage From b4782887e55b0341b98bab9579228f1ee135aaa8 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Tue, 22 Jul 2025 11:44:22 +0200 Subject: [PATCH 4/7] Clarifies extension method policy --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f7c3cab..7a43c28 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,16 @@ If you would like to contribute to this project, please submit a pull request. Use a namespace that reflects the utility's purpose. Choose names that are specific enough to be meaningful but generic enough to accommodate similar utilities in the future. -### Extension Method Restrictions +### Extension Method Policy -To prevent API pollution and naming conflicts, use static helper classes instead of extension methods for the following types: +Create utility methods as extension methods by default for discoverability and ease of use. + +**Exceptions - Use static helper classes for:** - All CLR primitives (`bool`, `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `nint`, `nuint`, `char`, `double`, `float`) -- Selected System .NET types: `string`, `decimal`, `object`, and `Enum` +- Selected System .NET types: `decimal`, `object`, and `Enum` -**Exception:** Extension methods that provide custom string representations are permitted, provided they follow the `ToXyzString()` naming convention, where `Xyz` clearly indicates the format or purpose of the output (e.g., `ToCurrencyString()`, `ToHexString()`). This ensures consistency and clarity in API design across the library. +**Exception to the exception:** Custom string representation methods (e.g., `ToCurrencyString()`, `ToHexString()`) are permitted as extension methods on the above types, using the `ToXyzString()` naming convention where `Xyz` describes the output format. ### Test Coverage From 4b6b73e9423138d1159c4489872eb30ca927dc16 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Mon, 28 Jul 2025 09:43:44 +0200 Subject: [PATCH 5/7] Update README Moves extension methods and helper classes to appropriate namespaces, --- .../FormFileExtensionsTests.cs | 1 + .../{ => Extensions}/FormFileExtensions.cs | 2 +- .../Files/FileSizeTests.cs | 2 +- .../CultureInfoExtensionsTests.cs | 2 +- .../Linq/EnumerableExtensionsTests.cs | 2 +- .../CultureInfoExtensions.cs | 2 +- .../EnumerableExtensions.cs | 2 +- .../{Files => Helpers}/FileSize.cs | 2 +- README.md | 20 ++++++++++++++++++- 9 files changed, 27 insertions(+), 8 deletions(-) rename Neolution.Utilities.AspNetCore/{ => Extensions}/FormFileExtensions.cs (94%) rename Neolution.Utilities/{Globalization => Extensions}/CultureInfoExtensions.cs (93%) rename Neolution.Utilities/{Linq => Extensions}/EnumerableExtensions.cs (96%) rename Neolution.Utilities/{Files => Helpers}/FileSize.cs (95%) diff --git a/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs b/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs index 9a7ba64..dfad45e 100644 --- a/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs +++ b/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs @@ -6,6 +6,7 @@ using System.Threading.Tasks; using AutoFixture; using Microsoft.AspNetCore.Http; + using Neolution.Utilities.AspNetCore.Extensions; using NSubstitute; using Shouldly; using Xunit; diff --git a/Neolution.Utilities.AspNetCore/FormFileExtensions.cs b/Neolution.Utilities.AspNetCore/Extensions/FormFileExtensions.cs similarity index 94% rename from Neolution.Utilities.AspNetCore/FormFileExtensions.cs rename to Neolution.Utilities.AspNetCore/Extensions/FormFileExtensions.cs index 7d5a35d..8b79f7a 100644 --- a/Neolution.Utilities.AspNetCore/FormFileExtensions.cs +++ b/Neolution.Utilities.AspNetCore/Extensions/FormFileExtensions.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.AspNetCore +namespace Neolution.Utilities.AspNetCore.Extensions { using Microsoft.AspNetCore.Http; diff --git a/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs b/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs index 0902e76..9aa1917 100644 --- a/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs +++ b/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs @@ -1,6 +1,6 @@ namespace Neolution.Utilities.UnitTests.Files { - using Neolution.Utilities.Files; + using Neolution.Utilities.Helpers; using Shouldly; using Xunit; diff --git a/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs b/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs index d6060ad..911e64b 100644 --- a/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs @@ -1,7 +1,7 @@ namespace Neolution.Utilities.UnitTests.Globalization { using System.Globalization; - using Neolution.Utilities.Globalization; + using Neolution.Utilities.Extensions; using Shouldly; using Xunit; diff --git a/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs b/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs index 1a8dfa3..8087ccb 100644 --- a/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs @@ -1,7 +1,7 @@ namespace Neolution.Utilities.UnitTests.Linq { using System.Collections.Generic; - using Neolution.Utilities.Linq; + using Neolution.Utilities.Extensions; using Shouldly; using Xunit; diff --git a/Neolution.Utilities/Globalization/CultureInfoExtensions.cs b/Neolution.Utilities/Extensions/CultureInfoExtensions.cs similarity index 93% rename from Neolution.Utilities/Globalization/CultureInfoExtensions.cs rename to Neolution.Utilities/Extensions/CultureInfoExtensions.cs index d003f40..4865da9 100644 --- a/Neolution.Utilities/Globalization/CultureInfoExtensions.cs +++ b/Neolution.Utilities/Extensions/CultureInfoExtensions.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.Globalization +namespace Neolution.Utilities.Extensions { using System.Globalization; diff --git a/Neolution.Utilities/Linq/EnumerableExtensions.cs b/Neolution.Utilities/Extensions/EnumerableExtensions.cs similarity index 96% rename from Neolution.Utilities/Linq/EnumerableExtensions.cs rename to Neolution.Utilities/Extensions/EnumerableExtensions.cs index 5b125bf..ec98672 100644 --- a/Neolution.Utilities/Linq/EnumerableExtensions.cs +++ b/Neolution.Utilities/Extensions/EnumerableExtensions.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.Linq +namespace Neolution.Utilities.Extensions { /// /// IEnumerable extensions diff --git a/Neolution.Utilities/Files/FileSize.cs b/Neolution.Utilities/Helpers/FileSize.cs similarity index 95% rename from Neolution.Utilities/Files/FileSize.cs rename to Neolution.Utilities/Helpers/FileSize.cs index 5d97a4b..c2ccc62 100644 --- a/Neolution.Utilities/Files/FileSize.cs +++ b/Neolution.Utilities/Helpers/FileSize.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.Files +namespace Neolution.Utilities.Helpers { /// /// Provides methods to get file sizes in human-readable formats. diff --git a/README.md b/README.md index 7a43c28..2f2d669 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,31 @@ This is a collection of utilities that we have created to help with our developm Add the NuGet package to your project and reference the desired classes in your source code. +## Additional Packages + +This library includes specialized packages that extend the core utilities for specific frameworks. These packages are deliberately separated from the base `Neolution.Utilities` package which remains framework-agnostic and dependency-free, ensuring it can be used in any .NET project without forcing unwanted dependencies. + ## Contributing If you would like to contribute to this project, please submit a pull request. ### Namespace Organization -Use a namespace that reflects the utility's purpose. Choose names that are specific enough to be meaningful but generic enough to accommodate similar utilities in the future. +To ensure clear and unambiguous contribution guidelines, organize utilities into the following namespaces based on their structure: + +- **`Neolution.Utilities.Extensions`** - for all extension methods +- **`Neolution.Utilities.Abstractions`** - for interfaces, base classes, and abstractions +- **`Neolution.Utilities.Helpers`** - for static utility classes + +### File Naming Guidelines + +- **Extensions**: Always `{Type}Extensions.cs` (e.g., `StringExtensions.cs`) +- **Abstractions**: Use descriptive names (e.g., `IValidator.cs`, `RetryPolicy.cs`) +- **Helpers**: Use clear, descriptive names that indicate the class purpose + +### Cross-Namespace Dependencies + +Extensions can reference Helpers and Abstractions when it makes sense for code reuse and maintainability. ### Extension Method Policy From 82c16f7a6273165b8c7653928c12680929910a00 Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Mon, 28 Jul 2025 09:52:29 +0200 Subject: [PATCH 6/7] rephrase --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f2d669..04279c4 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Add the NuGet package to your project and reference the desired classes in your ## Additional Packages -This library includes specialized packages that extend the core utilities for specific frameworks. These packages are deliberately separated from the base `Neolution.Utilities` package which remains framework-agnostic and dependency-free, ensuring it can be used in any .NET project without forcing unwanted dependencies. +This library includes specialized packages that extend the core utilities for specific frameworks and third-party libraries. These packages are deliberately separated from the base `Neolution.Utilities` package to maintain its framework-agnostic and dependency-free nature, ensuring it can be used in any .NET project without forcing unwanted dependencies. ## Contributing From 02d80745ca4dbb4c60492518b814b88e31129e3e Mon Sep 17 00:00:00 2001 From: Sandro Ciervo Date: Mon, 28 Jul 2025 17:05:11 +0200 Subject: [PATCH 7/7] cleanup --- .../{ => Extensions}/FormFileExtensionsTests.cs | 2 +- .../{Globalization => Extensions}/CultureInfoExtensionsTests.cs | 2 +- .../{Linq => Extensions}/EnumerableExtensionsTests.cs | 2 +- .../{Files => Helpers}/FileSizeTests.cs | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) rename Neolution.Utilities.AspNetCore.UnitTests/{ => Extensions}/FormFileExtensionsTests.cs (96%) rename Neolution.Utilities.UnitTests/{Globalization => Extensions}/CultureInfoExtensionsTests.cs (96%) rename Neolution.Utilities.UnitTests/{Linq => Extensions}/EnumerableExtensionsTests.cs (97%) rename Neolution.Utilities.UnitTests/{Files => Helpers}/FileSizeTests.cs (98%) diff --git a/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs b/Neolution.Utilities.AspNetCore.UnitTests/Extensions/FormFileExtensionsTests.cs similarity index 96% rename from Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs rename to Neolution.Utilities.AspNetCore.UnitTests/Extensions/FormFileExtensionsTests.cs index dfad45e..c1500f4 100644 --- a/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs +++ b/Neolution.Utilities.AspNetCore.UnitTests/Extensions/FormFileExtensionsTests.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.AspNetCore.UnitTests +namespace Neolution.Utilities.AspNetCore.UnitTests.Extensions { using System.IO; using System.Text; diff --git a/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs b/Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs similarity index 96% rename from Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs rename to Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs index 911e64b..0a05e6b 100644 --- a/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.UnitTests.Globalization +namespace Neolution.Utilities.UnitTests.Extensions { using System.Globalization; using Neolution.Utilities.Extensions; diff --git a/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs b/Neolution.Utilities.UnitTests/Extensions/EnumerableExtensionsTests.cs similarity index 97% rename from Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs rename to Neolution.Utilities.UnitTests/Extensions/EnumerableExtensionsTests.cs index 8087ccb..c5cf672 100644 --- a/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Extensions/EnumerableExtensionsTests.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.UnitTests.Linq +namespace Neolution.Utilities.UnitTests.Extensions { using System.Collections.Generic; using Neolution.Utilities.Extensions; diff --git a/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs b/Neolution.Utilities.UnitTests/Helpers/FileSizeTests.cs similarity index 98% rename from Neolution.Utilities.UnitTests/Files/FileSizeTests.cs rename to Neolution.Utilities.UnitTests/Helpers/FileSizeTests.cs index 9aa1917..e695e6a 100644 --- a/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs +++ b/Neolution.Utilities.UnitTests/Helpers/FileSizeTests.cs @@ -1,4 +1,4 @@ -namespace Neolution.Utilities.UnitTests.Files +namespace Neolution.Utilities.UnitTests.Helpers { using Neolution.Utilities.Helpers; using Shouldly;