适用于 Typescript 的代码整洁之道。 受到 clean-code-javascript 的启发。
目录
- 介绍
- 变量
- 函数
- Objects and Data Structures
- Classes
- SOLID
- Testing
- Concurrency
- Error Handling
- Formatting
- Comments
- Translations
介绍
软件工程原理，源自 Robert C. Martin's 的书 Clean Code, 适用于 TypeScript。 这不是风格指南，它是在 TypeScript 中生成 可读，可重用和可重构 软件的指南。
并非每个原则都必须严格遵守，普遍认同的甚至更少。这些只是准则，仅此而已，但他们却是 Clean Code 一书的作者根据自身多年的编程体会而提炼撰写出来的。
我们的软件工程技术只有50多年的历史，我们还有很多东西需要学习。当软件架构与架构本身一样古老时，也许那时我们会有更难遵循的规则。现在，让这些指导方针作为一个试金石，用来评估您和您的团队所生成的 Typescript 代码的质量.
除此之外：知道这些并不会立即使你成为一个更好的软件开发者，这些规则伴随你工作多年后并不意味着你就不会犯错误了。每一段代码都是作为初稿开始的，就像湿粘土被塑造成最终形状一样。最终，当我们与小伙伴们一起审查时，我们会凿掉不完美之处。不要因为这些需要改进的初稿而阻碍自己技术的提升。先干掉代码吧！
⬆ 返回顶部
变量
使用有意义的变量名
以这样的方式区分名称，以便读者知道他们的差异到底是什么。
反例:
function between<T>(a1: T, a2: T, a3: T): boolean {
return a2 <= a1 && a1 <= a3;
}
复制代码正例:
function between<T>(value: T, left: T, right: T): boolean {
return left <= value && value <= right;
}
复制代码⬆ 返回顶部
使用可拼读的变量名
如果你不能拼读他，你只能像个白痴一样去声明它。
反例:
type DtaRcrd102 = {
genymdhms: Date;
modymdhms: Date;
pszqint: number;
}
复制代码正例:
type Customer = {
generationTimestamp: Date;
modificationTimestamp: Date;
recordId: number;
}
复制代码⬆ 返回顶部
对于相同类型的变量只使用同一个单词
反例:
function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;
复制代码正例:
function getUser(): User;
复制代码⬆ 返回顶部
使用可搜索的名称
我们阅读的代码往往比我们要写的代码多。因此我们编写的代码的可读性和可搜索性是非常重要的。不给那些具有意义且有助于理解程序的变量命名，就会伤害了阅读代码的人。让您的名字可搜索。像 TSLint 这样的工具可以帮助识别未命名的常量。
反例:
// 86400000 到底是什么？
setTimeout(restart, 86400000);
复制代码正例:
// 将它们声明为大写的命名常量。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);
复制代码⬆ 返回顶部
使用变量展开
反例:
declare const users: Map<string, User>;
for (const keyValue of users) {
// 迭代用户地图
}
复制代码正例:
declare const users: Map<string, User>;
for (const [id, user] of users) {
// 迭代用户地图
}
复制代码⬆ 返回顶部
避免心照不宣
显式优于隐式。
清晰是王道。
反例:
const u = getUser();
const s = getSubscription();
const t = charge(u, s);
复制代码正例:
const user = getUser();
const subscription = getSubscription();
const transaction = charge(user, subscription);
复制代码⬆ 返回顶部
不要添加不需要的上下文
如果你的 类/类型/对象 名称中已经有说明，不要在你的变量中重复它们。
反例:
type Car = {
carMake: string;
carModel: string;
carColor: string;
}
function print(car: Car): void {
console.log(`${car.carMake} ${car.carModel} (${car.carColor})`);
}
复制代码正例:
type Car = {
make: string;
model: string;
color: string;
}
function print(car: Car): void {
console.log(`${car.make} ${car.model} (${car.color})`);
}
复制代码⬆ 返回顶部
使用默认参数而不是短路表达式或条件语句
默认参数通常比短路表达式更清晰。
反例:
function loadPages(count?: number) {
const loadCount = count !== undefined ? count : 10;
// ...
}
复制代码正例:
function loadPages(count: number = 10) {
// ...
}
复制代码⬆ 返回顶部