Enso项目TypeScript代码风格指南详解

Enso项目TypeScript代码风格指南详解

enso Hybrid visual and textual functional programming. 项目地址: https://gitcode.com/gh_mirrors/en/enso

前言

在大型软件开发项目中，统一的代码风格对于维护代码质量和团队协作至关重要。本文将深入解析Enso项目中的TypeScript代码风格规范，帮助开发者理解并遵循项目的最佳实践。

代码格式化规范

行宽限制

• 每行代码最多不超过100个字符（包括注释）
• 唯一例外：.tsx文件中的Tailwind类列表可以放在一行，且必须位于其他属性之后

导入分组规则

导入语句应分为5组，按以下顺序排列：

1. Node核心模块（带node:前缀）
2. React相关导入
3. 第三方库导入
4. 项目内其他包的导入
5. 相对路径导入

每组内部按字母顺序排序，使用命名空间导入或默认导入。

代码分段组织

代码应使用清晰的分段结构：

// ===============
// === 分段标题 ===
// ===============

// === 子分段标题 ===

每个文件至少应有一个分段，分段用于组织相关概念和实现。

垂直间距

• 函数、类和分段前后各空一行
• 文件末尾保留一个空行

多行表达式处理

优先考虑将复杂表达式拆分为多个单行表达式，使用有意义的变量名存储中间结果。

空格使用规范

• 类型操作符前后加空格
• 复杂表达式中的逗号后加空格
• 简单元素间的逗号后加空格
• 函数参数间加空格
• 运算符前后加空格

命名规范

• 类型：UpperCamelCase
• 变量和函数：camelCase
• 缩写词：全部小写（如makeHttpRequest）
• 短变量名限制：仅在无更好命名时使用
• 不安全操作：函数名需包含"unsafe"前缀
• 使用美式英语拼写

项目结构与访问控制

• 遵循Rust的包结构惯例
• 默认使用public修饰符
• 仅在可能破坏API内部保证时使用非公开访问控制

构建工具

• 使用npm进行项目管理
• 使用esbuild进行构建

注释规范

文档注释

用于公共API文档，包含：

1. 一行功能摘要
2. 可选详细描述

示例：

/**
 * 将树结构转换为序列表示
 * 
 * 提供可配置的遍历顺序选项，详见{@link WalkStrategy}
 */
walkToSequence(order: WalkStrategy<T>): T[] {
    // ...
}

源码说明

用于记录设计决策和复杂实现，格式为：

// 说明 [说明名称]
// ==============
// 详细说明内容...

TODO注释

格式要求：

// TODO [作者缩写] 说明待办事项
// FIXME [作者缩写] 说明需要修复的问题

程序设计原则

代码复杂度

• 优先编写简单、清晰的代码
• 避免过度设计
• 复杂逻辑应拆分为小函数

安全性

• 明确标记不安全操作
• 为不安全使用添加详细说明

测试与基准测试

• 重要功能需包含测试
• 性能关键代码应进行基准测试

警告与检查

• 启用所有编译器警告
• 使用lint工具保持代码质量

总结

Enso项目的TypeScript风格指南旨在创建一致、可读且易于维护的代码库。通过遵循这些规范，开发者可以专注于业务逻辑实现，而不必在代码风格上花费过多精力。记住，良好的代码风格最终目标是提升代码的可读性和可维护性，而非单纯遵守规则。

enso Hybrid visual and textual functional programming. 项目地址: https://gitcode.com/gh_mirrors/en/enso