Moving Beyond Angular's Style Guide - Part 3: Symbols and file names
Tags: angular, typescript, javascript, architecture
Published: 2020-04-08 13:18:24

---
title: Moving Beyond Angular's Style Guide - Part 3: Symbols and file names
published: true
description: Learn when we might adopt new symbols and file naming conventions in our Angular applications.
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/rkrji9mtuteq7s2ntfi0.jpg
tags: angular, typescript, javascript, architecture
series: Moving Beyond Angular's Style Guide
---

_In this series we look at some of the rules in [Angular's Style Guide](https://angular.io/guide/styleguide) that might need clarification or alteration as we grow our applications and our understanding 🧠 of the framework._

---

## 📐 The Rule in Question: [Symbols and file names](https://angular.io/guide/styleguide#symbols-and-file-names)

The Angular Style Guide defines this rule as follows:

> Do use consistent names for all assets named after what they represent.

> Do use upper camel case for class names.

> Do match the name of the symbol to the name of the file.

> Do append the symbol name with the conventional suffix (such as Component, Directive, Module, Pipe, or Service) for a thing of that type.

> Do give the filename the conventional suffix (such as .component.ts, .directive.ts, .module.ts, .pipe.ts, or .service.ts) for a file of that type.

---

## 💡 Positive Observations: Conventions are Convenient

The web framework Ruby on Rails popularized the idea of [Convention over Configuration](https://rubyonrails.org/doctrine/#convention-over-configuration), and while there aren't any naming conventions in Angular that replace configuration, using conventions is still important 😉.

In Angular's case the conventions aren't to help the framework - instead they help the developers.

Even when using a pattern like [micro frontends](https://martinfowler.com/articles/micro-frontends.html), we could end up with a large code base (or maybe multiple projects managed by [Nx](https://nx.dev/angular/getting-started/why-nx)).

Naming conventions with our files and Typescript types help us manage complexity in projects 🏗.

The conventions recommended by this rule of the style guide are also pretty easy to follow.

A component that lists users would have a file name of `users-list.component.ts` and a class name of `UsersListComponent`.

Other developers on our team, will quickly be able to understand the purpose of this file and class - we've encoded **helpful information**, in the file and class name, that we can **trust** because of the established project conventions.

If we instead named the file `all-users.ts` and the class name `UsersComp`, we lose the ability to quickly and easily identify that the file and class are connected, or even what the purpose of each are:

- Does `all-users.ts` contain a service or a component?
- Is `UsersComp` a component class type or something that can be "compared"?

If the project also contains classes ending in `*Component`, we could become even more confused 😵 - why was `UsersComp` used in the first place 🤷🏾‍♀️?

Since services and components fill distinct roles (business logic vs rendering state into markup), we want their purpose to be clear, with a convention we can trust.

---

## 👓 What Needs Clarification: Projects Can Have Conventions Beyond the Framework

The "Symbols and file names" rule mentions the following types of things:

- .component.ts, 
- .directive.ts, 
- .module.ts, 
- .pipe.ts
- .service.ts

This is no surprise, as these are all the types that Angular gives us to interact with the framework.

While still following the core idea of the style guide rule, we should not read it so literally. There are always going to be more types of things in our projects than what Angular provides with the framework!

> **If we are already using file and type names to encode helpful and trustworthy information into our code, we should extend these conventions beyond Angular's types.**

Let's look at a couple of examples we will likely encounter as our applications grow ...

### Models And Schemas

Angular is pretty hands-off when it comes to managing data, so it's up to us to clearly separate how we represent data inside and outside our application.

Schemas are a good way to represent the data of our application at the boundaries. This is often JSON exchanged with an API. Schemas are structured data only 🤔, they have no methods or functions.

#### user.schema.ts

```typescript
interface UserSchema {
  readonly id: string;
  readonly firstName: string;
  readonly lastName: string;
  readonly email: string;
}
```

Models represent the data of our application at the interior. They protect against [being changed into an inconsistent state](https://en.wikipedia.org/wiki/Class_invariant) and expose methods to enrich the data to match how our application operates 😮:

#### user.model.ts

```typescript
class User implements UserSchema {
    
  get fullName(): string { return `${this.firstName} ${this.lastName}`; }

  constructor(
    public readonly id: string,
    public readonly firstName: string,
    public readonly lastName: string,
    public readonly email: string) { }
}
```

### Container Components, Presentation Components, and Presenters

If we consider adopting the [Model, View, Presenter](https://indepth.dev/model-view-presenter-with-angular/) pattern in our application architecture, we will end up with several new types not mentioned in Angular's style guide.

[Container components](https://indepth.dev/container-components-with-angular/) "supply a data flow for presentation" and "translate component-specific events to application state commands or actions to put it in Redux/NgRx Store terms".

[Presentational components](https://indepth.dev/presentational-components-with-angular/) "present application state to the user" and "Change application state triggered by user interaction".

[Presenters](https://indepth.dev/model-view-presenter-with-angular/#presenters) are services that contain "behavioural logic and complex presentational logic" extracted from our Presentational components.

Here's an example of the file and type names we might have using this pattern:

- Container component
  - `UsersContainerComponent`, `users.container.ts`
- Presentational component
  - `UsersUiComponent`, `users-ui.component.ts`
- Presenter service
  - `UsersPresenter`, `users.presenter.ts`

### State Management Libraries

We can also find examples of non-Angular types when using state management libraries.

[Akita](https://netbasal.gitbook.io/akita/core-concepts/store) uses "Stores" and "Queries"

- Users store
  - `UsersStore`, `users.store.ts`
- Users query
  - `UsersQuery`, `users.query.ts`

[NgRx](https://ngrx.io/guide/store/actions#writing-actions) uses "Actions", "Reducers", "Stores", and "Selectors". NgRx 

- Users action
  - `LoadUsersAction`, `users-store/actions.ts`
- Users secltor
  - `selectActiveUsers`, `users-store/selectors.ts`

Each of these libraries might have [their own conventions](https://netbasal.gitbook.io/akita/other/best-practices) or [conventions](https://itnext.io/ngrx-best-practices-for-enterprise-angular-applications-6f00bcdf36d7) created [by the community](https://github.com/orizens/ngrx-styleguide/blob/master/docs/reducers.md).

---

## ✨ Conclusion

The main takeaway for all of us is to use type names that are consistent with our team, organization, or project 🤗.

Notice how many of the names of the above types don't fall into any of the categories supplied by Angular.

Angular is focused mainly on helping us convert application state into a user interface, but there will always be parts of our application not related to creating HTML 🧐.

For these types, we have an opportunity...

We should develop _our own_ conventions, and the most important part is not that the conventions match the Angular style guide, but that they are **consistently applied** 👍🏿.

> That said, aligning as much as possible with the Angular style guide makes our projects more consistent with the larger Angular community, which makes them more understandable and familiar to new developers joining our team.

> It's probably best not to name a component that displays users a `UserCollectionDisplayer`, even if it's a consistently applied convention in our project.

We can still use `.component.ts` , `.pipe.ts` , `.service.ts` but let's not be so dogmatic about it 😎, and explore conventions for "Symbols and file names" that work best for the functionality and complexity of our projects.

As always, thanks for reading 🙏!

---

## ❓ Questions

What are your thoughts on the conventions detailed by the "Symbols and file names" rule?

Can deviations or additions to Angular's style guide be in alignment with it's all-in-one, framework focused ethos?

Have you already adopted any custom naming conventions in your Angular projects?

Do you have some recommendations new symbol and file names that the community could adopt?

Leave a comment below!

---

<figcaption>Cover photo by <a href="https://unsplash.com/@crisdinoto">Cris DiNoto</a> on Unsplash</figcaption>

---

Normally, I'm blogging about [Kentico](https://www.kentico.com/), a content management system I love to use.

We've put together a list over on [Kentico's GitHub account](https://github.com/Kentico/Home/blob/master/RESOURCES.md) of developer resources. Go check it out!

If you are looking for additional Kentico content, checkout the Kentico tag here on DEV:

{% tag kentico %}

Or my Kentico blog series:

- [Kentico 12: Design Patterns](https://dev.to/search?q=Kentico%2012%3A%20Design%20Patterns)
- [Kentico CMS Quick Tips](https://dev.to/search?q=Kentico%20CMS%20Quick%20Tip)
- [Kentico EMS: MVC Widget Experiements](https://dev.to/search?q=Kentico%20EMS%20-%20MVC%20Widget%20Experiments)