From 85bcaf742946170a28878f26fde7381b0baa5901 Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Mon, 20 Apr 2026 10:44:22 -0600
Subject: [PATCH] Add guideline for defining the name of a controller

There is no written standard for defining the name of a controller, and
some contributors do not have a common understanding of the do's and
dont's for the name.

This commit adds such a guideline, highlighting the following points:

- The name of a controller should be defined in a variable called
  `CONTROLLER_NAME` (formerly `controllerName`)
- The name should be used to define custom actions and events and should
  be passed to `BaseController`
- The name should not be exported from the package
---
 docs/code-guidelines/controller-guidelines.md | 157 ++++++++++++++++++
 .../src/sample-gas-prices-controller.ts       |  12 +-
 .../src/sample-petnames-controller.ts         |  12 +-
 3 files changed, 169 insertions(+), 12 deletions(-)

diff --git a/docs/code-guidelines/controller-guidelines.md b/docs/code-guidelines/controller-guidelines.md
index 6367a1a50d7..556203c7c78 100644
--- a/docs/code-guidelines/controller-guidelines.md
+++ b/docs/code-guidelines/controller-guidelines.md
@@ -372,6 +372,163 @@ rootMessenger.subscribe('FooController:someEvent', () => {
 });
 ```
 
+## Define, but do not export, a name for the controller
+
+Every controller has a name, which is not only used to namespace the controller's messenger actions and events, but also to namespace the controller's state data when composed with other controllers.
+
+The name should be defined in a constant called `CONTROLLER_NAME` so that it can be easily changed if the need arises. (This variable was formerly called `controllerName`.) The name should be used to initialize the messenger, and should also be passed to the `BaseController` constructor.
+
+The constant should be used to define actions and events. It may be exported from the file in which it is defined, but should not listed as an export of the package:
+
+🚫 **The messenger namespace is not defined as a constant, but is repeated**
+
+```typescript
+export type FooControllerSomeCustomAction = {
+  type: 'FooController:someCustomAction';
+  handler: (bar: string) => void;
+};
+
+export type FooControllerAnotherCustomAction = {
+  type: 'FooController:anotherCustomAction';
+  handler: (baz: number) => void;
+};
+
+export type FooControllerActions =
+  | FooControllerSomeCustomAction
+  | FooControllerAnotherCustomAction;
+
+export type FooControllerMessenger = Messenger<
+  'FooController',
+  FooControllerActions,
+  never
+>;
+
+export class FooController extends BaseController</* ... */ {
+  constructor(/* ... */) {
+    super({ name: 'FooController', /* ... */ })
+
+    // ...
+  }
+}
+```
+
+🚫 **The messenger namespace is defined as a constant, but it is called `controllerName`**
+
+```typescript
+const controllerName = 'FooController';
+
+export type FooControllerSomeCustomAction = {
+  type: `${typeof controllerName}:someCustomAction`;
+  handler: (bar: string) => void;
+};
+
+export type FooControllerAnotherCustomAction = {
+  type: `${typeof controllerName}:anotherCustomAction`;
+  handler: (baz: number) => void;
+};
+
+export type FooControllerActions =
+  | FooControllerSomeCustomAction
+  | FooControllerAnotherCustomAction;
+
+export type FooControllerMessenger = Messenger<
+  typeof controllerName,
+  FooControllerActions,
+  never
+>;
+
+export class FooController extends BaseController</* ... */ {
+  constructor(/* ... */) {
+    super({ name: controllerName, /* ... */ })
+
+    // ...
+  }
+}
+```
+
+🚫 **The messenger namespace is defined as a constant, but it is exported from the package**
+
+```typescript
+/* packages/foo-controller/src/foo-controller.ts */
+
+export const CONTROLLER_NAME = 'FooController';
+
+export type FooControllerSomeCustomAction = {
+  type: `${typeof CONTROLLER_NAME}:someCustomAction`;
+  handler: (bar: string) => void;
+};
+
+export type FooControllerAnotherCustomAction = {
+  type: `${typeof CONTROLLER_NAME}:anotherCustomAction`;
+  handler: (baz: number) => void;
+};
+
+export type FooControllerActions =
+  | FooControllerSomeCustomAction
+  | FooControllerAnotherCustomAction;
+
+export type FooControllerMessenger = Messenger<
+  typeof CONTROLLER_NAME,
+  FooControllerActions,
+  never
+>;
+
+export class FooController extends BaseController</* ... */ {
+  constructor(/* ... */) {
+    super({ name: CONTROLLER_NAME, /* ... */ })
+
+    // ...
+  }
+}
+
+/* packages/foo-controller/src/index.ts */
+
+export {
+  CONTROLLER_NAME,
+  FooController
+} from './foo-controller';
+```
+
+✅ **The messenger namespace is defined as a constant, and it is kept internal instead of being exported**
+
+```typescript
+/* packages/foo-controller/src/foo-controller.ts */
+
+const CONTROLLER_NAME = 'FooController';
+
+export type FooControllerSomeCustomAction = {
+  type: `${CONTROLLER_NAME}:someCustomAction`;
+  handler: (bar: string) => void;
+};
+
+export type FooControllerAnotherCustomAction = {
+  type: `${CONTROLLER_NAME}:anotherCustomAction`;
+  handler: (baz: number) => void;
+};
+
+export type FooControllerActions =
+  | FooControllerSomeCustomAction
+  | FooControllerAnotherCustomAction;
+
+export type FooControllerMessenger = Messenger<
+  CONTROLLER_NAME,
+  FooControllerActions,
+  never
+>;
+
+export class FooController extends BaseController</* ... */ {
+  constructor(/* ... */) {
+    super({ name: CONTROLLER_NAME, /* ... */ })
+
+    // ...
+  }
+}
+
+/* packages/foo-controller/src/index.ts */
+
+export { FooController } from './foo-controller';
+```
+
 ## Expose controller methods through messenger in bulk
 
 Exposing controller methods through the messenger can be tedious. An action type must be created for each method, each action type must be added to the messenger type, and each action must be registered through the messenger. This creates a lot of boilerplate that must be maintained.
diff --git a/packages/sample-controllers/src/sample-gas-prices-controller.ts b/packages/sample-controllers/src/sample-gas-prices-controller.ts
index 770a94c449e..c354c90da3f 100644
--- a/packages/sample-controllers/src/sample-gas-prices-controller.ts
+++ b/packages/sample-controllers/src/sample-gas-prices-controller.ts
@@ -22,7 +22,7 @@ import type { SampleGasPricesServiceFetchGasPricesAction } from './sample-gas-pr
  * controller's actions and events and to namespace the controller's state data
  * when composed with other controllers.
  */
-export const controllerName = 'SampleGasPricesController';
+const CONTROLLER_NAME = 'SampleGasPricesController';
 
 // === STATE ===
 
@@ -94,7 +94,7 @@ const MESSENGER_EXPOSED_METHODS = ['updateGasPrices'] as const;
  * Retrieves the state of the {@link SampleGasPricesController}.
  */
 export type SampleGasPricesControllerGetStateAction = ControllerGetStateAction<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SampleGasPricesControllerState
 >;
 
@@ -117,7 +117,7 @@ type AllowedActions =
  */
 export type SampleGasPricesControllerStateChangeEvent =
   ControllerStateChangeEvent<
-    typeof controllerName,
+    typeof CONTROLLER_NAME,
     SampleGasPricesControllerState
   >;
 
@@ -138,7 +138,7 @@ type AllowedEvents = NetworkControllerStateChangeEvent;
  * {@link SampleGasPricesController}.
  */
 export type SampleGasPricesControllerMessenger = Messenger<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SampleGasPricesControllerActions | AllowedActions,
   SampleGasPricesControllerEvents | AllowedEvents
 >;
@@ -219,7 +219,7 @@ export type SampleGasPricesControllerMessenger = Messenger<
  * ```
  */
 export class SampleGasPricesController extends BaseController<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SampleGasPricesControllerState,
   SampleGasPricesControllerMessenger
 > {
@@ -246,7 +246,7 @@ export class SampleGasPricesController extends BaseController<
     super({
       messenger,
       metadata: gasPricesControllerMetadata,
-      name: controllerName,
+      name: CONTROLLER_NAME,
       state: {
         ...getDefaultSampleGasPricesControllerState(),
         ...state,
diff --git a/packages/sample-controllers/src/sample-petnames-controller.ts b/packages/sample-controllers/src/sample-petnames-controller.ts
index 4124688f96d..a8b18844537 100644
--- a/packages/sample-controllers/src/sample-petnames-controller.ts
+++ b/packages/sample-controllers/src/sample-petnames-controller.ts
@@ -17,7 +17,7 @@ import type { SamplePetnamesControllerMethodActions } from './sample-petnames-co
  * controller's actions and events and to namespace the controller's state data
  * when composed with other controllers.
  */
-export const controllerName = 'SamplePetnamesController';
+const CONTROLLER_NAME = 'SamplePetnamesController';
 
 // === STATE ===
 
@@ -70,7 +70,7 @@ const MESSENGER_EXPOSED_METHODS = ['assignPetname'] as const;
  * Retrieves the state of the {@link SamplePetnamesController}.
  */
 export type SamplePetnamesControllerGetStateAction = ControllerGetStateAction<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SamplePetnamesControllerState
 >;
 
@@ -91,7 +91,7 @@ type AllowedActions = never;
  */
 export type SamplePetnamesControllerStateChangeEvent =
   ControllerStateChangeEvent<
-    typeof controllerName,
+    typeof CONTROLLER_NAME,
     SamplePetnamesControllerState
   >;
 
@@ -112,7 +112,7 @@ type AllowedEvents = never;
  * {@link SamplePetnamesController}.
  */
 export type SamplePetnamesControllerMessenger = Messenger<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SamplePetnamesControllerActions | AllowedActions,
   SamplePetnamesControllerEvents | AllowedEvents
 >;
@@ -167,7 +167,7 @@ export type SamplePetnamesControllerMessenger = Messenger<
  * ```
  */
 export class SamplePetnamesController extends BaseController<
-  typeof controllerName,
+  typeof CONTROLLER_NAME,
   SamplePetnamesControllerState,
   SamplePetnamesControllerMessenger
 > {
@@ -189,7 +189,7 @@ export class SamplePetnamesController extends BaseController<
     super({
       messenger,
       metadata: samplePetnamesControllerMetadata,
-      name: controllerName,
+      name: CONTROLLER_NAME,
       state: {
         ...getDefaultPetnamesControllerState(),
         ...state,