[Proposal] Update Namespaces to Match Folder Structure

Update Namespaces to Match Folder Structure

• Proposed
• Prototype
• Implementation: Not Started
  • iOS Support
  • Android Support
  • macOS Support
  • Windows Support
• Unit Tests: Not Started
• Sample: Not Started
• Documentation: Not Started

Link to Discussion

Discussion on Namespaces Matching Folder Structure

• https://github.com/CommunityToolkit/Maui/pull/214/files#r768099127 Discussion on Moving Enums to a folder called Enums, and updating their namespaces accordingly
• https://github.com/CommunityToolkit/Maui/pull/214/files#r767382464

Summary

This Proposal solves two problems:

• Ensures a file’s namespace matches its folder hierarchy
• Moves Enums to their own File in an Enums folder

Because this is a breaking change that requires XAML users to add additional xmlns, this Proposal will be placed on hold until a Toolkit-wide namespace is introduced in #144, e.g. xmlns:toolkit="http://schemas.microsoft.com/dotnet/2021/maui/tookit".

Motivation

Currently, both CommunityToolkit.Maui and CommunityToolkit.Maui.Core use the root folder for their namespace, but nested folders are not included.

E.g. /Behaviors/EventToCommandBehavior.shared.cs uses namespace CommunityToolkit.Maui.Behaviors; E.g. /Behaviors/Validators/CharactersValidationBehavior.shared.cs also uses namespace CommunityToolkit.Maui.Behaviors;

This root-folder namespace matches the precedent set in Xamarin.CommunityToolkit, however, we would like to follow the industry-standard of matching the folder hierarchy.

Detailed Design

• Update Namespaces to match folder structure
  • E.g. /Behaviors/Validators/CharactersValidationBehavior.shared.cs will become namespace CommunityToolkit.Maui.Behaviors.Validators;
• Add IDE0130 to DirectoryBuild.props
  • <WarningsAsErrors>nullable,CS1574,IDE0130</WarningsAsErrors>
  • This ensures that all future PRs will have namespaces that match the file’s folder hierarchy
• Create Enums Folder, and move each enum types into their own file in this folder
• Currently, all single-use Enums are placed in the same file as the class that uses them

Drawbacks

• Breaks precedence set by Xamarin.CommunityToolkit
• Will require XAML users to set an additional xmlns
  • This is averted by holding this Proposal until #144 is completed
• Will require C# users to declare an additional using CommunityToolkit.Maui.* namespace

Alternatives

There are two other alternatives:

1. Matching the Assembly namespace

• Every file in CommunityToolkit.Maui would use namespace CommunityToolkit.Maui
• Every file in CommunityToolkit.Maui.Core would use namespace CommunityToolkit.Maui.Core

1. Matching Xamarin.CommunityToolkit’s Precedence of Root-Folder Namespaces

Unresolved Questions

None that I can think of

[brminnick]

Good question!

Looks like there are 3 Options being discussed:

1. Matching the Folder Structure
2. Matching only the Assembly namespace
   • Every file in CommunityToolkit.Maui would use namespace CommunityToolkit.Maui
   • Every file in CommunityToolkit.Maui.Core would use namespace CommunityToolkit.Maui.Core
3. Matching the Root-Folder Namespace
   • This matches Xamarin.CommunityToolkit’s Precedence of Root-Folder Namespaces

Let’s do a vote:

1. React with a ❤️ to vote for Option 1
   • Matching the Assembly + Folder Structure
2. React with a 🚀 to vote for Option 2
   • Matching only the Assembly namespace
3. React with a 👀 to vote for Option 3
   • Matching the Root-Folder Namespace

Edit: Adding EmailValidationBehavior Example 👇

Option 1 ❤️

namespace CommunityToolkit.Maui.Behaviors.Validators;

public class EmailValidationBehavior

Option 2 🚀

namespace CommunityToolkit.Maui;

public class EmailValidationBehavior

Option 3 👀

namespace CommunityToolkit.Maui.Behaviors;

public class EmailValidationBehavior

[michael-hawker]

In the Windows Community Toolkit we’ve found that flattening namespaces down helps with reducing the amount of usings required in discovering what’s available to use. This is also important for anything that needs to be included in XAML as having a bunch of xmlns is confusing and unwieldly, so we’ve been trying to reduce that as well.

@Sergio0694 any insights from the .NET Community Toolkit you’d want to share?