为了文档的规范化,统一性,可维护性,以及良好的阅读体验。我们决定制定一些规范。
请所有人都重视该规范,因为这可能影响你的提交内容是否被采用,哪怕是你的内容很值得被采用。
在文章主体语言是中文的情况下,大体上使用中文标点。
在文章主体语言是英文的情况下,大体上使用英文标点。
中文字符,与非中文字符(不包含标点符号)之间需要一个空格的间距。
正确:
这是一个 template。 这真的是一个
template
。
错误:
这是一个template。 这真的是一个
template
。
正确:
这周六刚好是 1024 节耶!
错误:
这周六刚好是1024节耶!
但使用百分号(%) / 度(°)为单位时,不需要 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>
终于要写完了!
用法:
「老师,『有条不紊』的『紊』是什么意思?」
对比用法:
“老师,‘有条不紊’的‘紊’是什么意思?”
为了文档的可读性,建议尽可能地添加相关的图示。
每份文档中的引用图片,为了尽可能保证访问的有效性和方便维护,建议尽可能在项目中存放。
存储位置:该文档所在路径下名为 Img
的文件夹。这样分门别类的对应存放,方便后续的维护。
文件名命名方式:
模板:<引用文档文件名><贴图时间(年月日时分)> 示范:
规范手册202010200721
假如你使用 VS Code 进行编写 MarkDown 文档,有个插件可以协助你实现我们的这一约定:
安装好后,在其插件设置中的 Markdown-image > Local: Path
选项配置内容中写入 ./Img
,如图所示。假设不自定义设置,你的贴图则默认会存放在整个项目的根目录下名为 images
文件夹下
并在图片引用 MarkDown 语法内容中的 []
,写上简单描述。
.gitignore
规范进阶
因为在文档编辑时,可能你会使用一些会在项目根目录下自动生成配置文件的文档编辑器(比如,Obsidian),或者是与项目内容无关的文件。
请务必第一时间将它们在 Git 中忽略!务必!请永远不要提交它们!
如何在 Git 中忽略某些指定文件,或者某些指定文件夹下的所有文件呢?
你需要用到一个名为 .gitignore 的文件,并在其中写入想要忽略的文件/文件夹的相对路径,一行一个。
该文件我已在项目根目录下创建,你只需要在其中按要求写入内容即可。
相关文档:gitignore - Specifies intentionally untracked files to ignore
基础模板:
type
(scope
):crude explanation
类型
(范围
):粗略的描述
注意:
()
!:
,且后面跟有一个空格!**type:该 commit 所代表的操作类型,只允许使用下面几个标识:
Scope:该 commit 所影响的文件范围。
若存在多个单词,使用所有字母都小写,以下划线连接的 snake 命名格式。
只允许使用以下标识规则:
router/index.js
,scope 则为 router
.粗略性的表述你这次代码修改操作,力求言简意赅。
可中文可英文。
通过反馈而做出的修改/修复
init(global): 初始化项目 style(home_page): 修改样式 change(pay_bill): 变动支付流程
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。