1 Star 1 Fork 0

max-studio / CMT_CS_Learning

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
规范手册.md 8.58 KB
一键复制 编辑 原始数据 按行查看 历史

规范手册

为了文档的规范化,统一性,可维护性,以及良好的阅读体验。我们决定制定一些规范。

请所有人都重视该规范,因为这可能影响你的提交内容是否被采用,哪怕是你的内容很值得被采用。

1. 文档排版规范

中英文标点

在文章主体语言是中文的情况下,大体上使用中文标点。

  • 若有插入完整的英文语句/段落,则在其中使用英文标点。
  • 不得混用。

在文章主体语言是英文的情况下,大体上使用英文标点。

  • 若有插入完整的中文语句/段落,则在其中使用中文标点。
  • 不得混用。

空格

中文字符,与非中文字符(不包含标点符号)之间需要一个空格的间距。

中英文之间需要 1 个空格

正确:

这是一个 template。 这真的是一个 template

错误:

这是一个template。 这真的是一个template

中文与数字之间需要 1 个空格

正确:

这周六刚好是 1024 节耶!

错误:

这周六刚好是1024节耶!

数字与单位之间需要 1 个空格

但使用百分号(%) / 度(°)为单位时,不需要 1 个空格

正确:

当前的网速为 10.65 MB/s。 今天的环境湿度为 39%,温度回暖 20% 的趋势。 一周角分为 360 等份,每份定义为 1 度(1°)。

错误:

当前的网速为 10.65MB/s。 今天的环境湿度为 39 %,温度回暖 20% 的趋势。 一周角分为360等份,每份定义为1度(1 °)。

中文标点与其他字符之间不加空格

正确:

今天是周一,全新一周的开始。

错误:

今天是周一 , 全新一周的开始。

标点符号

不要重复使用标点符号

正确:

今天居然是周一了!?又要开始上班了!

错误:

今天居然是周一了!??又要开始上班了!!!

破折号与非中文标点之间需要增加一个空格

正确:

你看啊 —— 一个小黄鸭出现在马路上 做一件事,无论大小,倘无恒心,是很不好的。—— 鲁迅

错误:

你看啊 —— 一个小黄鸭出现在马路上 做一件事,无论大小,倘无恒心,是很不好的。——鲁迅

省略号

正确:

根正苗红的省略号是长这样的:……

错误:

错误的省略号:....../。。。。。。

数字使用半角字符

正确:

今天是 2020 年 10 月 26 日

错误:

今天是 2020 年 10 月 26 日

遇到完整的英文整句、特殊名词,其內容使用半角标点

正确:

乔布斯那句话是怎么说的?「Stay hungry, stay foolish.」

推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》,非常的有趣。

错误:

乔布斯那句话是怎么说的?「Stay hungry,stay foolish。」

推荐你阅读《Hackers&Painters:Big Ideas from the Computer Age》,非常的有趣。

名词

专有名词,默认使用官方全称,不得缩写!

专有名词,未作特殊说明时,皆使用官方全称,不得缩写!

不要使用不地道的缩写

正确:

我们需要一位熟悉 JavaScript、HTML5,至少理解一种框架(如 Backbone.js、AngularJS、React、Vue 等)的前端开发者。

错误:

我们需要一位熟悉 Js、h5,至少理解一种框架(如 backbone、angular、RJS、vue 等)的 FED。

其他

斜体文字使用加出样式代替

正确:

斜体本身是为西文文字所设计,为了保持良好的阅读效果,在中文排版时不应出现斜体,因此统一使用加粗样式代替。

错误:

斜体本身是为西文文字所设计,为了保持良好的阅读效果,在中文排版时不应出现斜体,因此统一使用加粗样式代替。

使用留空一行进行换行

使用留空一行进行换行,不得使用 <br> 进行换行。

要写完了!

终于要写完了!

错误:

要写完了!<br> 终于要写完了!

简体中文使用直角引号

用法:

「老师,『有条不紊』的『紊』是什么意思?」

对比用法:

“老师,‘有条不紊’的‘紊’是什么意思?”

2. 引用图片规范

为了文档的可读性,建议尽可能地添加相关的图示。

每份文档中的引用图片,为了尽可能保证访问的有效性和方便维护,建议尽可能在项目中存放。

存储位置:该文档所在路径下名为 Img 的文件夹。这样分门别类的对应存放,方便后续的维护。

图片存放演示

文件名命名方式:

模板:<引用文档文件名><贴图时间(年月日时分)> 示范: 规范手册202010200721

辅助性插件

假如你使用 VS Code 进行编写 MarkDown 文档,有个插件可以协助你实现我们的这一约定:

Markdown Image

Markdown Image

安装好后,在其插件设置中的 Markdown-image > Local: Path 选项配置内容中写入 ./Img ,如图所示。假设不自定义设置,你的贴图则默认会存放在整个项目的根目录下名为 images 文件夹下

Markdown Image 相关设置

并在图片引用 MarkDown 语法内容中的 [],写上简单描述。

3. .gitignore 规范进阶

因为在文档编辑时,可能你会使用一些会在项目根目录下自动生成配置文件的文档编辑器(比如,Obsidian),或者是与项目内容无关的文件。

请务必第一时间将它们在 Git 中忽略!务必!请永远不要提交它们!

如何在 Git 中忽略某些指定文件,或者某些指定文件夹下的所有文件呢?

你需要用到一个名为 .gitignore 的文件,并在其中写入想要忽略的文件/文件夹的相对路径,一行一个。

该文件我已在项目根目录下创建,你只需要在其中按要求写入内容即可。

相关文档:gitignore - Specifies intentionally untracked files to ignore

代码提交信息规范

基础模板:

type(scope): crude explanation

类型(范围): 粗略的描述

注意

  • 模板中的括号必须为英文括号 ()
  • 冒号为英文冒号 :,且后面跟有一个空格!**

Type

type:该 commit 所代表的操作类型,只允许使用下面几个标识:

软件协作开发

  • feat:实现新功能
  • fix:修复一切错误,不只是代码 bug
  • docs:文档改变
  • style:样式修改
  • change:小范围且不影响主体功能的需求性修改
  • delete:删除文件/模块
  • package:依赖的改动
  • refactor:某个已有功能重构
  • perf:性能优化,代码内容完善
  • test:增加测试
  • build:生成打包文件/改变了 build 工具如 grunt 换成了 npm
  • revert:撤销上一次的
  • commitchore:构建过程或辅助工具的变动,比如 把 npm 换成了 yarn

文档库协作

  • add:新增内容板块,可以是大类,可以是具体的
  • update:更新文档内容
  • fix:纠正文档内容错误,修复链接错误跳转、合并错误之类的错误
  • delete:删除文件/文件夹/内容模块
  • refactor:重构文件结构,重新划分内容分类
  • finish:完成某文档/计划

Scope

Scope:该 commit 所影响的文件范围。

若存在多个单词,使用所有字母都小写,以下划线连接的 snake 命名格式。

只允许使用以下标识规则:

  • 影响全局:global
  • 因为某个目的而修改了多个文件:该功能下的主体文件夹名
  • 只修改了一个文件:默认该文件名(不需要文件后缀名)。若该文件名在多个文件夹下存在同名文件,则写文件夹名。比如:router/index.js,scope 则为 router.

Crude Explanation

粗略性的表述你这次代码修改操作,力求言简意赅。

  • 可中文可英文。

    • 若写英文,首单词首字母必须小写,其后单词视情况确定大小写格式。
  • 通过反馈而做出的修改/修复

    • 通过 issue 反馈,在 Commit Message 结尾带上 issue 链接
    • 通过邮件反馈,在 Web 端带上邮件大致内容

示范

init(global): 初始化项目 style(home_page): 修改样式 change(pay_bill): 变动支付流程

参考文献

译文排版规则指北

1
https://gitee.com/max-studio/CMT_CS_Learning.git
git@gitee.com:max-studio/CMT_CS_Learning.git
max-studio
CMT_CS_Learning
CMT_CS_Learning
main

搜索帮助