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
调用和定义都可以是 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
の 之
ɵ 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 也是对的。
