代码规范

目的与范围

本文档定义了30秒代码项目的编码标准、风格指南和最佳实践。它确立了在仓库内所有编程语言中编写、格式化和记录代码片段的一致约定。这些标准确保了代码的质量、可读性和可维护性。

有关贡献流程的信息，请参阅贡献指南。

写作指南概述

30秒代码项目遵循特定的写作指南，以在所有内容中保持一致性。这些指南适用于代码和文档。

语言和语态

方面	指南
拼写	使用美式英语拼写
句子长度	保持句子简短（最好不超过20个词）
重点	每句话应有一个焦点
语态	优先使用主动语态而非被动语态
技术术语	仅在必要时使用行业标准术语
方向性语言	尽可能避免使用方向性引用（例如，“上方”、“下方”）
祈使语态	在记录代码片段时使用祈使语态

代码文档

在记录代码片段时

使用祈使语态（例如，“使用此方法”）
避免使用允许性语言（例如，“您可以使用此方法”）
将行内代码块包裹在适当的视觉元素中
将重要值（数字、字符串、布尔值）包裹在适当的视觉元素中
使用多行代码块来处理跨越多行的代码
为多行代码块提供适当的语言上下文和高亮
在描述原生代码时，使用全称或最接近官方文档的名称

来源：CONTRIBUTING.md88-95

代码结构和组织

项目内容结构

30秒代码仓库的内容结构遵循特定模式，该模式能够实现代码片段的无缝分类和发现。

图示：仓库中的内容组织

来源：CONTRIBUTING.md14

代码片段结构

每个代码片段都遵循一致的结构，以确保统一性和可读性。

图示：代码片段文件结构

来源：CONTRIBUTING.md14

代码内容标准

代码质量要求

代码片段必须满足以下质量要求：

功能性：代码必须按描述工作并处理边缘情况
清晰性：代码应清晰易懂
简洁性：解决方案应简洁，但不牺牲可读性
可重用性：在适当的情况下，代码应可重用
文档：所有代码必须有充分的文档记录

特定语言的标准

该项目支持多种编程语言，每种语言都有自己的一套标准和最佳实践。这些通常包括：

遵守语言约定
正确的错误处理
性能考量
使用现代语言特性

文档标准

内容结构

文档遵循特定结构，以确保清晰度和一致性。

章节	目的
标题	代码片段的清晰、描述性名称
描述	解释代码片段的作用和何时使用
代码	带有适当语法高亮的实现
示例	通过示例输入/输出来演示用法
注释（可选）	其他信息、边缘情况或限制

标题和列表

将标题的第一个单词大写，如果格式化为句子，其余部分小写
如果未格式化为句子，可以大写每个单词的首字母
保持标题简短（一行以内）
标题应信息丰富且描述性强
尽可能使用项目符号（无序）列表
对步骤序列使用编号（有序）列表
列表项应以大写字母开头

来源：CONTRIBUTING.md104-120 CONTRIBUTING.md122-132

代码高亮标准

代码高亮遵循特定规则，以确保可读性和一致性。

图示：代码高亮过程

代码高亮的关键实践

使用适当的语言标识符进行语法高亮
为相似的代码元素提供一致的高亮
必要时高亮重要部分或行
包含适当的元信息（标题、行高亮）
确保代码元素之间有足够对比度
遵循特定语言的高亮约定

来源：CONTRIBUTING.md88-95

语言和风格指南

大写

大写句子开头的字母，其余字母小写
保留术语（例如，“JavaScript”）、首字母缩略词、产品和商标的原始大小写
对于标题，将第一个单词大写，或者如果未格式化为句子，则将每个单词的首字母大写

标点符号

在正文中避免使用连字符（&）；改用拼写“and”
使用撇号表示省略的字母、缩写或所有格
使用引号来定义单词或引用的文本
避免在句子中间使用句点，除非在代码内部或作为术语的一部分
谨慎使用冒号，主要用于引出列表
在句子中不要使用牛津逗号
尽可能不使用分号

强调

谨慎使用粗体来强调重要信息
不要使用粗体创建标题
使用斜体来引用文本，通常是简短的逐字短语
在需要特别强调的较长句子时，使用引文块

代码引用

将行内代码块包裹在适当的视觉元素中
将重要值（数字、字符串、布尔值）包裹在适当的视觉元素中
使用多行代码块来处理跨越多行的代码
为多行代码块提供语言上下文和高亮
在描述原生代码时，使用全称或最接近官方文档的名称
不要在标题中使用代码块

来源：CONTRIBUTING.md43-46 CONTRIBUTING.md49-66 CONTRIBUTING.md74-80 CONTRIBUTING.md88-95

贡献工作流程

为30秒代码项目贡献代码的工作流程遵循以下步骤：

图表：贡献工作流程

贡献时，请遵循以下关键规则：

对他人保持礼貌和尊重
遵循维护者的建议
在修改网站内容时，仅修改content/snippets或content/collections目录下的文件

来源：CONTRIBUTING.md11-14

基本规则

违反任何这些规则将导致您的拉取请求被关闭。

始终对他人保持礼貌和尊重，并尽量遵循维护者的建议。
在修改网站内容时，仅修改content/snippets或content/collections目录下的文件。