Lee's opinions on Umbraco + naming things

Naming things is hard (maybe?)

Text casing styles

Note: I'll be mentioning different text casing styles in this article. In case you aren't aware of these, here's a quick primer...

Lexicon the different text casing styles

These are the different text casing styles for naming things like folders, files, URLs, variables, etc. Along with the typical UPPERCASE, lowercase, Title Case and Sentence case, there are also...

• PascalCase - spaces removed, each word is capitalised, (popularized by the Pascal language).
• camelCase - same as PascalCase, but starts with lowercase, (because the capitals look like camel humps).
• kebab-case - spaces replaced with hyphens/dashes, generally lowercase, (named on a late Saturday night after the pub closed).
• snake_case - spaces replaced with underscores, generally lowercase, (named after some slippery character).

For further explanation on these text casings, take a read of freeCodeCamp's article on What's the Difference Between Casings?.

General naming of things

For anything that is going to be a public-facing web-asset, e.g. folders, filenames, anything that'll become a URL, then I go with kebab-case (lowercase) all the way.

In the early 2000s, the GOV.UK team (Alphagov back then, now GDS), released a bunch of guidelines on file naming, the kebab-case one stuck in my mind. Unfortunately, I can't find a link to the original document.

For Visual Studio projects, the folder structure would generally correspond C# namespaces and types, so they'd be in PascalCase.

For C# variables names; camelCase, but I still underscore prefix _ for private backing fields, (old habits die hard).

Namespaces

From my early .NET and XML days I learnt about the importance of clear and decisive namespaces. To be treated like a classification system, (scoped however you need, e.g. per project, per organisation, for global usage). I'd spend a silly amount of time deliberating on the namespace taxonomy for my code libraries.
It's like creating your own mini Dewey Decimal system.

For Visual Studio/.NET projects and libraries, I follow the general .NET convention of dot-delimited, capitalised/PascalCase namespaces.

Nowadays, especially for any Umbraco extensions I develop, I try to follow Umbraco's own namespaces as closely as possible. e.g. I'd put my custom IContentFinder classes under a [Brand].Web.Routing namespace. Mostly so that it feels logical for any other developers who may be familiar with Umbraco core code.

.NET libraries

As I start planning out an ASP.NET website, I try to judge how much application code it will need. For basic brochureware websites, there may be an odd API controller, so I'll end up placing that code within the website itself, (for legacy ASP.NET, I'd put it in App_Code; for .NET Core, it'd be in the main project, pre-compiled).

When there is more application code required, I'd separate out code into additional library dependencies, which needs to be named - what do I call them?

Historically, I'd go with initially adding a [Brand].Core library, and whack everything in there. Then if needed, separate out larger features to their own libraries. But what do I call them?

As mentioned in the previous section, with my Umbraco work, I'd been following a similar namespace pattern to Umbraco CMS itself.
I'd typically start off with naming my main project as [Brand].Web, this would house the Umbraco CMS instance, the Razor views, wwwroot, and not much else.

For the public-facing, website specific code, (including Surface/API controllers, ViewComponents, extension methods, etc). I'd name that [Brand].Cms.Web.Website library (as Umbraco has a corresponding named library).

For any CMS backoffice specific code, e.g. property-editors, dashboards, notification handlers, (maybe even a custom Contentment Data List source), etc. I'd name this [Brand].Cms.Web.BackOffice.

If there is application code that needs to be shared between the Website and the BackOffice libraries, e.g. generated ModelsBuilder classes, Configuration classes; I'd go with having a shared library called [Brand].Cms.Web.Common.

For any additional features, say a 3rd-party integration, then I'd follow similar to how Umbraco have done with their Umbraco.Cms.Integrations.* packages, so for a MailChimp integration, I'd go with [Brand].Cms.Integrations.MailChimp; or a YouTube integration, [Brand].Cms.Integrations.YouTube.

For something that is more short-lived, such as a pre-launch content migration using uSync Migrations, that may require custom code, I'd have a standalone [Brand].Cms.ContentMigration library, so that it can easily be removed prior to launch/production.

NuGet packages

Most often when naming a NuGet package, you'd go with whatever the name of your Visual Studio project library is, they fall hand-in-hand. However, if you named your library something simple, say after a generic English word, or something that has no context outside of your scope/project, then it can look messy.

I try to take a worldview; think globally. 🌍

Many developers prefix their package ID with their organisation's name; this is quite common, good advertising and totally acceptable.

With open-source Umbraco community-related NuGet packages, I've seen several misnamed packages, but not to pick faults with others, I'll keep focus on my own mistakes. Let's take uComponents (circa 2010), as the name may imply, it's a bunch of components for Umbraco, (hence the u-prefix, part of a trend of packages around that time; uCommerce, uBlogsy, uCssClassNameDropdown, uSync, etc), it made sense, it was a good brand name. The Visual Studio project was named uComponents, so when we made the NuGet package, the obvious choice was, you guessed it, uComponents! 🤦

Why is this a problem? At face value, it isn't a problem. Taking a step back at a more global level, what does "uComponents" mean to the rest of the world? Many of the .NET developers who heavily use NuGet may have not even heard of Umbraco CMS, let alone a 3rd party plugin for it. What if people from the Uno Platform community are browsing NuGet for some kind of components extension library? You can see, this could get confusing outside the scope of the Umbraco community/ecosystem.
On top of this, uComponents was developed against Umbraco v4, with its last release in 2016, now it's there to be lingering on the NuGet repository until the end of time, set in stone.

After that I started to prefix my package names under something more scoped to the context of the Umbraco ecosystem, a la Our.Umbraco.*.

You can read an old post of mine about the History of "Our.Umbraco.*" package names.

More recently, Umbraco HQ allowed use of the Umbraco.Community.* prefix, which I've use for my Contentment package and I actively advocate other package developers to do the same.

GitHub repositories

Given the name of a public GitHub repository is part of its URL, I'll use kebab-case. Additionally, I'll include a prefix to set the scope/context/namespace of the repository itself, this would typically be the primary technology used, e.g. umbraco-contentment.

My reasoning behind this, is for GitHub's approach to repository forking. Let's take for example Umbraco's RFCs repo, umbraco/rfcs; the name of the organisation is umbraco and the name of the repository is rfcs, (all makes sense!). If I were to fork this repo, (which I have), then that would become leekelleher/rfcs, losing it's context of it being about Umbraco - so I'd personally rename my fork to leekelleher/umbraco-rfcs.

Does it matter? In the greater schemes probably not, but I prefer the semantics of such naming.

The majority of my GitHub repositories are Umbraco-related, so mostly have an umbraco- prefix, but if I was developing a dependency-free library in a specific language/framework, I'd used whatever prefix deemed relevant, e.g. dotnet-, php-, wordpress-, etc.

Umbraco CMS schema style guide

I wanted to briefly touch on naming things in Umbraco CMS itself, e.g. the schema: Document Types, Property Types, Templates, etc.

For Document Types and Property Types, I try to keep the names as Sentence case, (not Title Case), I used to do this, but I tried out (Sentence case) and it felt more natural and friendly to read. With the aliases, these are camelCase by default, no arguments there. As for the descriptions, I try to write simple/plain English summaries, avoiding any technical jargon.

Document Type icon colours. I try to have a consistency based on the content type, e.g. Compositions are Lime; Pages (nodes in the tree) are Indigo; Element Types/Blocks are Blue-Grey. (I dunno, it makes me happy).

Further reading

If you're interested in how things are named in other web-tech, here are a few links for further reading...

• HTML5 spec on Common idioms
• Code Guide by Mark Otto, Standards for developing consistent, flexible, and sustainable HTML and CSS.