Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

docs: add naming convertion (#1890)

Wenzhao Huf80ed5de3024
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 24641efd39..343826dc15 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -85,7 +85,7 @@ During the refactoring process, it is recommended to remove legacy folders such
Avoid creating barrel imports (index.ts) unless it is the main root index.ts file of a plugin.
-### Contextual Connections
+### Connecting context
To effectively contribute as a member of a software engineering team (and community as well!), it is crucial to establish strong contextual connections. Providing links to relevant resources can greatly assist others in understanding the context. Consider the following practices:
@@ -95,26 +95,9 @@ To effectively contribute as a member of a software engineering team (and commun
By adopting these practices, you can enhance collaboration and facilitate a better understanding of the codebase within our community.
-### Naming conventions
+### Naming convention
-To ensure code quality and consistency, please adhere to the following guidelines:
-
-- Use kebab-case for both file names and folder names. If the file contains a React component, it should be in PascalCase, e.g. `SheetTab.tsx`.
-- Folder names should be in plural format.
-- Interfaces should be named starting with a capital "I".
-- Do use conventional type names including .service, .controller, .menu, .command, .mutation, and .operation. Invent additional type names if you must but take care not to create too many.
-
-Sometimes you need to defined a dependency injection token. Please adhere to the following naming convention:
-
-```typescript
-export const IYourServiceOrControllerName = createIdentifier<IYourServiceOrControllerName>('<package-name>.<your-service-or-controller-name>.(service|controller)');
-```
-
-For example:
-
-```typescript
-export const ILogService = createIdentifier<ILogService>('core.log.service');
-```
+Please refer to [Univer Naming Convention](./docs/NAMING_CONVENTION.md).
### Submitting pull requests
@@ -186,4 +169,4 @@ npm create @univerjs/cli init <project-name>
## Links
-* [How to Contribute to Facade API](./packages/facade/docs/CONTRIBUTING.md)
+* [How to Contribute to Facade API](./packages/facade/docs/CONTRIBUTING.md)
\ No newline at end of file
diff --git a/docs/NAMING_CONVENTION.md b/docs/NAMING_CONVENTION.md
new file mode 100644
index 0000000000..c2a1c0fa11
--- /dev/null
+++ b/docs/NAMING_CONVENTION.md
@@ -0,0 +1,138 @@
+# Univer Naming Convention
+
+To ensure code quality and consistency, please adhere to the following guidelines.
+
+## Files & Folders
+
+Use kebab-case for both file names and folder names. If the file contains a React component, it should be in PascalCase. For example:
+
+```txt
+// ✅
+src/
+ components/
+ my-component/
+ my-util.ts
+ MyComponent.tsx
+
+// 🚫
+src/
+ components/
+ myComponent/
+ myUtil.ts
+ my-component.tsx
+```
+
+Folder names should be in plural format. Files names should be in singular format. For example:
+
+```txt
+// ✅
+src/
+ services/
+ util.ts
+
+// 🚫
+src/
+ service/
+ utils.ts
+```
+
+Do use conventional type names including .service, .controller, .menu, .command, .mutation, and .operation. Invent additional type names if you must but take care not to create too many. For example:
+
+```txt
+// ✅
+src/
+ services/
+ log.service.ts
+ user.service.ts
+ controllers/
+ log.controller.ts
+ user.controller.ts
+```
+
+## Interfaces
+
+Interfaces should be named starting with a capital "I". For example:
+
+```typescript
+// ✅
+export interface IMyInterface {}
+
+// 🚫
+export interface MyInterface {}
+```
+
+## Dependency Injection Token
+
+Sometimes you need to defined a dependency injection token. Please adhere to the following naming convention:
+
+```typescript
+export const IYourServiceOrControllerName = createIdentifier<IYourServiceOrControllerName>('<package-name>.<your-service-or-controller-name>.(service|controller)');
+```
+
+For example:
+
+```typescript
+// ✅
+export const ILogService = createIdentifier<ILogService>('core.log.service');
+
+// 🚫
+export const ILogService = createIdentifier<ILogService>('log-service');
+```
+
+## Plugins' Names
+
+Plugin names should be all in capitalized letters and suffixed by `PLUGIN`. Words should be separated by underscores and suffixed. For example:
+
+```typescript
+// ✅
+export const SHEET_CONDITIONAL_FORMATTING_PLUGIN = 'SHEET_CONDITIONAL_FORMATTING_PLUGIN';
+
+// 🚫
+export const SHEET_CONDITIONAL_FORMATTING_PLUGIN = 'SHEET_CONDITIONAL_FORMATTING';
+
+// 🚫
+export const SHEET_CONDITIONAL_FORMATTING_PLUGIN = 'sheet-conditional-formatting-plugin';
+```
+
+### Plugins' classes
+
+Plugin classes should be named in PascalCase and prefixed by `Univer`. For example:
+
+```typescript
+// ✅
+export class UniverFilterPlugin extends Plugin {}
+
+// 🚫
+export class FilterPlugin extends Plugin {}
+```
+
+### Resource key
+
+Resource keys should reuse the corresponding plugin's name.
+
+## Commands
+
+Commands' names should follow the convention below:
+
+```typescript
+export interface ISomeCommandParams {
+ // Define the parameters here
+}
+export const SomeCommand = ICommand<ISomeCommandParams> = {
+ id: '<business-type>.<command-type>.<command-name>',
+};
+```
+
+For example:
+
+```typescript
+// ✅
+export const SetSelectionFrozenCommand: ICommand<ISetSelectionFrozenCommandParams> = {
+ id: 'sheet.command.set-selection-frozen',
+}
+
+// 🚫
+export const SetSelectionFrozenCommand: ICommand<ISetSelectionFrozenCommandParams> = {
+ id: 'SetSelectionFrozenCommmand',
+}
+```
\ No newline at end of file