Naming conventions

[Conaclos]

Context

For now, Rome has only one rule to check consistent naming convention: useCamelCase which is certainly inspired by its equivalent ESLint rule camel-case.

Some users proposed the addition of new rules : usePascalCaseClassNames.

TypeScript ESLint implements an all-in-one rule: naming-convention.
The rule has a default behavior and is fine-tunable (AST node type, regex, ...).

I personally did not like the multiplication of rules: useCamelCase, usePascalCaseClassNames, useConstantCase, ...
On the other hand, I did not like the fine-tunable all-in-one rule.

I suggest introducing a new rule useConventionalName or useNamingConvention that ensures the respect of naming conventions in the JS/TS community.
The rule should be sufficiently relaxed in order to accommodate with the current practice in the community.

In the following section I gathered the naming practice.

Conventional name

Please feel free to comment in this thread if I missed something.

1. An identifier is in PascalCase, camelCase, or CONSTANT_CASE.

2. An identifier can be prefixed with underscores _.

   This supports several practices:

   • Old-fashion way marking a property as private
   • Marking a variable/function as intentionally unused
   • Marking a function as a test utility (recognized by some test frameworks).
   • underscore / lodash namespace
   • Placeholder
   • special property such as React's __html

3. An identifier can be suffixed with underscores _.

   This allows compatibility with the default behavior of ESLint naming-convention.

4. An identifier can be prefixed with dollar signs $.

   This supports several practices:

   • regex matches:

   s.replace(/^(\w)\w/, ($0, $1) => $1.toUpperCase())

   • JQuery namespace

5. An identifier can be suffixed with dollar signs $.

   This supports one practice:

   • Observable stream.

   conts myObservable$ = ...

On top of these simple rules, we add some restrictions:

Naming style	Category
PascalCase	class / enum / interface / type alias / type parameter
PascalCase or camelCase	named function / namespace
camelCase	class property / function parameter / local variable / object property / top-level let / method / module alias
camelCase or CONSTANT_CASE	static class property / static class getter / readonly type property / type getter
PascalCase or camelCase or CONSTANT_CASE	import and export aliases / enum value (configured) / top-level const / top-level var

Some remarks:

• All values that are types (class, enum, enum value, interface, type alias, type parameter) can be in PascalCase

• Named function in PascalCase

  In contrast to the default behavior of ESLint nameing-convention, I think we should allow named function in PascalCase.
  This allows:

  • old-fashion ES5 classes

  • React components:

    function GoLink(props: GoLinkProps) { return <a href={...}>... }

  • @Decoarator

• static class property / getter in CONSTANT_CASE

  In contrast to the default behavior of ESLint nameing-convention, we allow static class property in CONSTANT_CASE.
  This is often used to denote a class constant.

• interface / type readonly property / getter in CONSTANT_CASE

  This allows to model the interface of the sttatic part of a class.

• Top-level variables can be in CONSTANT_CASE or PascalCase

  In contrast to the default behavior of ESLint nameing-convention, only top-level variables of a script, module, or namespace declared with const or var can be in CONSTANT_CASE or PascalCase.

• An enum value is either in UpperCamelCase or in CONSTANT_CASE

  We find these two naming conventions in the community.
  UpperCamelCase seems more widely used than CONSTANT_CASE.

  Strangely, the default behavior of ESLint nameing-convention requires using camelCase.
  This seems to confuse users.
  I opened an issue about that.

Configuration

• strictCase: allow supporting consecutive uppercase chars in camelCASE and PascalCASE. In strict case mode (default) HTTPServer is not considered in PascalCase. It has to be renamed to HttpServer.

• enumMemberCase: allow choosing between PascalCase (default), CONSTANT_CASE, and camelCase (for _ESlint8 compatibility).

[Conaclos]

I am not sure if this should be part of the same rule. However, we can add a convention for filenames.

Conventional filenames for JavaScript and TypeScript

Please feel free to comment in this thread if I missed something.

The rule applies to all files ending with the following extensions: ts, tsx, cts, mts, js, jsx, cjs, mjs, .d.ts, .d.cts, .d.mts.

1. A filename is in file-name or file_name.

   These two conventions are widely used.

2. A filename can start with a single underscore _.

   This supports several practices:

   • internal-only modules
   • test utilities

3. The filename extension can be preceded by a secondary extension: .test, .spec.

   This is widely supported by test frameworks.

Configuration

An option should be provided to choose between file-name or file_name. I am not sure about which default we should adopt. _internal_module.js seems nicer than _internal-module.js. However, it is pretty rare to use underscore prefixing and it is often used with a single word such as _internal.js. file-name seems more URL-ish. This seems a good thing since imports are URLs.

[jpike88]

as a data point we use -, never _ in our filenames. As you say it's probably cause it's more of a natural URL-like convention

[Conaclos]

Otherwise, we could accept the two conventions by default. The option could restrict to one of these two conventions.

[ematipico]

A filename is in file-name or file_name.

These two conventions are widely used.

Unfortunately there are more cases.

Many projects use camelCase style to name their files (check astro, to name one).

Also, another pattern used is PascalCase for:

• files that contain components (react, preact, etc.)
• files that export a single class; check projects that use ORMs like typeorm, projects that use nestjs. It's a style that comes from OOP;

[Conaclos]

I did not start the rule for filenames. I noticed that Rome codebase use PascalCase for components and classes.

I have to check if these projects mix different cases for their filenames. If it is the case, we could provide a configuration that allows several cases. If the community is widely divided we could allow by default all widespread cases (snake_case, kebab-case, camelCase, PascalCase). However, this seems a bit too permissive?

We could differently treat PascalCase by checking that the file exports a function or a class named with the same name (or any named entity with this name). I am not sure about that, because this could mean that the rule checks the content of the file. What do you think?

[ematipico]

I like this proposal very much. It could be a rule under style group, opt-in. Now that the rules can access the SourceType and the Path of a file, I think have everything to start its implementation!

[Conaclos]

I will work on this :) By the way, I think we should separate it in two rules: one for js/ts names and the other for filenames. What do you think?

[ematipico]

I leave the decision to you! There are some case where naming a file comes from what's exported. For example

export default class FooController {}

If this file exports only a class, can we suggest FooController.js?

I don't mind splitting the logic or making one single rule. The only restrain we have is the fact that we can't suggest a code fix that changes the name of file. So maybe it could make sense to have two rules.

[Conaclos]

I updated the spec with the current implementation of the rule.

EDIT: I am thinking about enabling PascalCase for top-level const / var. This could be consistent with import/export renaming style and allow to alias a class / component function.

I am wondering if we should also accept local variables / parameters / top-level let in PascalCase as well to highlight the fact that a variable aliases a class / component?

However, for consistency, this could also require supporting PascalCase for object / type / class properties and getters.

We could add some restrictions: for instance we could allow PascalCase for local variable if an anonymous function, an anonymous class, or another variable in PascalCase is the assigned value.
However, this looks a bit complex and partial (we cannot check parameters).

I could like to get opinions about this.

[ematipico]

Strangely, the default behavior of ESLint nameing-convention requires using lowerCamelCase.
This seems to confuse users.
I opened an issue about that.

Have you tried to see if Rust/clippy throws a warning if we write an enum variant in lower case? I would tend to follow the rules set by a language that has first class support for enums

[Conaclos]

Rust advocates Pascal Case.

The rationale of TypeScript for promoting PascalCase over CONSTANT_CASE is that it is both a value and a type. Flow type also advocates PascalCase. Some styling guide such as Google's one, advocate for CONSTANt_CASE.

I really don't know where the camelCase convention of ESLint comes from. This looks like an undersight...

[ematipico]

Yeah, I've never seen a lower case approach before :/

You're right, I don't think we should follow their lead in this case. Good call out!

[Conaclos]

By the way, I added camelCase in the possible values for enumMeberCase config. This allows compatibility with ESLint.