Naming Conversion & Case Style 命名规范

前言

写代码有 2 个点很重要

第一是表达 (不要词不达意)

要达到这点, 就要多参考其它人如何表达.

第二是一致性 (一样的东西就用一样的写法)

要达到这点就要建立规范

以前的笔记

命名规范 naming conversion, camel case, pascal case, hyphen 等等

ASP.NET Core – Case Style Conversion

Case Style

pascal case = PascalCase

camel case = camelCase

kebab case = kebab-case (通常是 lower case)

snake case = snake_case

upper case = UPPERCASE

lower case = lower case

title case = Blog Title

以下是我自己的规范和学习笔记

Url Case Style

Url 用 kebab-case

query params 用 snake_case (oauth) 或 camelCase (gmail),

我选 camelCase 因为 ASP.NET Core 用 action parameter 来获取 route param 而它是 camelCase

Folder and File Case Style

参考一些开源库:

.NET = PascalCase

Angular = forlder: kebab-case, file: snake_case

Angular Material = kebab-case

React = forlder: kebab-case, file: camelCase

Vue = folder: kebab-case, file: PascalCase or camelCase

Me = need url access: kebab-case, 前端: kebab-case, 后端: PascalCase,

Folder and File Path Naming Conversion

参考:

What is the naming standard for path components?

FileRootFullPath = C:\Project\Hydro\wwwroot\uploaded-files\image.jpg

FileFullPath = wwwroot\uploaded-files\image.jpg (从 Project 走起, 而不是 C drive, 不一定是 wwwroot, 这里只是一个 example)

FileName = image.jpg

FileNameWithoutExtension = image

Extension = .jpg

DirectoryName = uploaded-files (和 .net 有分歧)

DirectoryRootFullPath = C:\Project\Hydro\wwwroot\uploaded-files

DirectoryFullPath = wwwroot\uploaded-files

RelativePath = ./ or ../

AbsolutePath = ~/abc/xyz

DirectoryPath = "abc\xyz"

Folder vs Directory

folder 通常是用在 UI 上, 程序基本上都会叫 directory(目录). 参考: stackoverflow – What is the difference between a directory and a folder?

C# Case Style

class name = PascalCase

property name = PascalCase

enum = PascalCase

filed = camelCase

private field = _camelCase

variable = camelCase

parameter = camelCase

local function = PascalCase

Tuple

ValueTuple naming conventions

调用和定义都可以是 PascalCase or camelCase.

如果调用的时候是当 object 用, 那么 property 就应该是 PascalCase. 如果是当解构 variables 用, 那就是 camelCase 合理些.

关键点是, 定义的时候用 PascalCase, 调用 property ok, variables 就 rename, 也 ok.

定义用 camelCase, 调用 property 就坏掉了.

所以定义的时候用 PascalCase 会好一点, 但如果可以确定使用时是 variables, 那我觉得定义时用 camelCase 也是可以的. 比如用 Tuple 做 Action 的 parameters 的时候.

ASP.NET Core Case Style

async method should suffix?

Razor Pages use async suffix

Web API don't use async suffix

Razor Pages handler 

官网的例子是

/external-login?handler=AccessDenied

/customer?handler=delete

单字就 lowercase, 多字就 PascalCase

我个人觉得, 统一用 PascalCase 会更好.

JS / TS Case Style

class name = PascalCase

enum = PascalCase

property name = camelCase

variable = camelCase

parameter = camelCase

custom dom event name = lowercase (follow 原生)

localStorage key = camelCase

其它:

可传递函数 endswith Fn e.g. compareFn (这个是 follow Angular 的, 以前我是放 compareFunc 的)

要不要 window prefix ? window.setTimeout or just setTimeout ?

如果用 TypeScript 的话，setTimeout 和 window.setTimeout 是不一样的，window.setTimeout 返回的是 number 类型，setTimeout 返回的是 NodeJS.Timeout。

所以我目前的做法是用之前先 F12 看看

如果 NodeJS 有而且和 window 一样类型那些，那我就不写 prefix window。

如果 NodeJS 没有，或者类型和 winodw 不同，那就 prefix window。

想通过 eslint 管理, 可以参考这个 Github – Is there a rule that requires "window." when accessing global?

SQL Case Style

database name = PascalCase

table name = PascalCase (Singular)

column name = PascalCase

query = UPPERCASE

variable = PascalCase

trigger name for redundacy = TR_TableName_AfterInsert_ForRedundancy_TableName_ColumnName (第 1 个 table name 是被监听的, 第 2 个是冗余 table)

trigger name for cascade = TR_TableName_InsteadOfDelete_ForCascade_TableName (第 1 和第 2 table name 是一样的)

抽象的 array 和 object 命名

EPPlus 叫 foreach (var item in collection)

有些人叫 foreach (var obj in objects)

有些人叫 foreach (var data in dataList)

我选 EPPlus

 

HTML Id and Class Name

kebab-case

其它

cachedInfo (Angular Component)

cloned element (Angular Component)

sortingDisabled (Angular Component)

a 乘 b 我用 multiply 而不是 times (C# decimal.Multiply vs big.js  times)

FileName and fileName 而不是 Filename and filename (Angular 两个都用但是 FileName/fileName 占多数, C# 用的也是 FileName)

Google Analytics event name = lower kebab-case

DateCreated, CreatedBy, DateModified, ModifiedBy (from Windows)

操作符号的命名

equals (Google Ads), equal to (Excel), =

not equals (Google Ads), not equal to (Excel), <> (Excel), !=, ≠  (alt 2260 | 8800, 都不可以的话就 看这里, copy 比较快)

contains

does not contain (结尾没有 s, Google Ads style)

starts with ^ (正则)

ends with $ (正则)

less than <

less than or euqal to <= (Google Ads, Excel), ≤

greater than >

greather than or equal to  >= (Google Ads, Excel), ≥

between 0..2 (double dot, Dynamics 365 style), 0–2 (en dash), 0-2 (hyphen)

null, empty

个人觉得倾向 Excel 会不错

符号和命名

[] = brackets = square brackets

() = parentheses = round brackets

{} = culy brackets

<> = angle brackets or chevrons

- hyphen

– en dash (alt + 0150)

— em dash (alt + 0151)

° degree (alt + 0176)

² power 2 (alt 0178)

³ power 3 (alt 0179)

ⁿ power n (alt 252)

≥ greater than or equal (alt 242)

≤ less than or equal (alt 243)

trademark

trademark

≼ class extends

→ function return

’ single quotation mark (alt 0146)

の 之

ɵ theta，Angular 用它表示 internal 变量和函数

oData vs odata

它的名字是 OData, 遇到要 camelCase 的时候就变成 oData 但是看上去又有点怪, 于是就可能是 odata

查了一下源码发现 2 个他们都有用. 统一用 odata 吧.

 

当遇上 Acronym / Initialism 缩写

遇到 Acronym 缩写, 比如 NASA, RAM, ZIP 非常的烦.

很难 convert 的漂亮和有规范.

我们好好分析一下到底该怎样做，有哪些方便会收到影响.

眼睛分割

SystemIO, PersonDTO 如果缩写是在最后. 那么你会发现它没有那么碍眼.

CADDesigner, PersonDTOValidator 在前面和中间就非常碍眼, 关键就是分割不到.

CADDesigner DD 要分开，但是 2 个都大写, 眼睛就分不开了

PersonDTOValidator OV 要分开, 一样的问题.

可还原性

CADDesigner to TitleCase = CAD Designer (right)

Cad Designer to TitleCase = Cad Designer (wrong)

在转 TitleCase 的时候, 如果没有保留全大写, 转换结果是不理想的

Asp.net Core 默认行为

ASP.NET Core – Case Style Conversion

转 camelCase 时, 它会处理前面的缩写, 但后面的不会, .

CADDesigner -> cadDesigner, but PersonDTO -> personDTO

大家的建议

C# naming conventions for acronyms

如果是 2 个字母, 那么就保留大写, 比如 IO, 超过 2 个字母就变大小写

还有

目前的结果是

Acronym 在后面, 保留大写, 转换美美, 分割美美

Acronym 在中间, 保留大写, 转换美美, 分割丑丑

Acronym 在前面 camelCase, 一定是小写, 转换丑丑, 分割美美

Acronym 在前面 PascalCase, 保留大写, 转换美美, 分割丑丑

总结

在后面, 建议保留大写. 可转换, 分割也 ok

在中间, 可转换, 可分割, 2 选一, 平手

在前面, 如果是 camelCase 那转换是不可能的了, 只能是选可分割.

所以统一的话, 就是选可分割，但是不可转换 (TitleCase), 它的硬伤就是 camelCase 一定是小写开头, 缩写全都变小了, 可能不可还原了.

ID vs Id

微软的 SQL Server example 使用 ID

EF Core 用 Id

其它参考

我选 Id

lowercase vs lowerCase

ASP.NET Core Identity

RequireLowercase，RequireUppercase

JavaScript string extensions

.toLowerCase，.toUpperCase

双方不统一。我 follow 双方吧。

各大名词

有些名词是不规范的, 但如果遇到要自动 convert 的话, 建议还是 follow 规范比较方便. 这些是比较纠结的

YouTube: PascalCase: YouTubePlayer, camelCase : youtubePlayer (参考: Angular YouTube Player 源码)

我最讨厌这种不能 convert 的字, 所以我一律用 Youtube 而不是 YouTube

WhatsApp: PascalCase: WhatsApp, camelCase: whatsapp, camelCase: whatsAppNumber

它用在 kebab-case 的地方是 whats-app, 虽然很多人会用 whatsapp 但是不能 convert 很麻烦的, 所以我个人依然用 whats-app

Times vs Multiply

在用 big.js 时，它有 2 个一样功能的方法。

new Big(11).times(12);
new Big(11).mul(12);

mul 是 times 的别名

mul 是 alias 意味着 times 应该是 default 比 mul 多人使用，但是 mul 的人数肯定也不少，不然干嘛搞 alias。

C# 有个方法是

decimal.Multiply(11, 12);

我 research 了一下，最后看到了这个解释。

well, times is generally used in between two numbers, like "three times six" and multiply is usually used before them, so you would say "multiply three and six". you can put the two together and say " multiply three times six".

所以

new Big(11).times(12);

比较合理，而 C# 的 decimal.Multiply 也是对的。