diff --git a/Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs b/Neolution.Utilities.AspNetCore.UnitTests/Extensions/FormFileExtensionsTests.cs similarity index 93% rename from Neolution.Utilities.AspNetCore.UnitTests/FormFileExtensionsTests.cs rename to Neolution.Utilities.AspNetCore.UnitTests/Extensions/FormFileExtensionsTests.cs index 9a7ba64..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; @@ -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/Globalization/CultureInfoExtensionsTests.cs b/Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs similarity index 93% rename from Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs rename to Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs index d6060ad..0a05e6b 100644 --- a/Neolution.Utilities.UnitTests/Globalization/CultureInfoExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Extensions/CultureInfoExtensionsTests.cs @@ -1,7 +1,7 @@ -namespace Neolution.Utilities.UnitTests.Globalization +namespace Neolution.Utilities.UnitTests.Extensions { 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/Extensions/EnumerableExtensionsTests.cs similarity index 95% rename from Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs rename to Neolution.Utilities.UnitTests/Extensions/EnumerableExtensionsTests.cs index 1a8dfa3..c5cf672 100644 --- a/Neolution.Utilities.UnitTests/Linq/EnumerableExtensionsTests.cs +++ b/Neolution.Utilities.UnitTests/Extensions/EnumerableExtensionsTests.cs @@ -1,7 +1,7 @@ -namespace Neolution.Utilities.UnitTests.Linq +namespace Neolution.Utilities.UnitTests.Extensions { using System.Collections.Generic; - using Neolution.Utilities.Linq; + using Neolution.Utilities.Extensions; using Shouldly; using Xunit; 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 0902e76..e695e6a 100644 --- a/Neolution.Utilities.UnitTests/Files/FileSizeTests.cs +++ b/Neolution.Utilities.UnitTests/Helpers/FileSizeTests.cs @@ -1,6 +1,6 @@ -namespace Neolution.Utilities.UnitTests.Files +namespace Neolution.Utilities.UnitTests.Helpers { - using Neolution.Utilities.Files; + using Neolution.Utilities.Helpers; 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 463b50c..04279c4 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,52 @@ 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. + +## Additional Packages + +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 + If you would like to contribute to this project, please submit a pull request. -### Guidelines +### Namespace Organization + +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 -- 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. +Extensions can reference Helpers and Abstractions when it makes sense for code reuse and maintainability. + +### Extension Method Policy + +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: `decimal`, `object`, and `Enum` + +**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 + +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.