# zh-programmer-document-guide

**Repository Path**: LeoLeeTech/zh-programmer-document-guide

## Basic Information

- **Project Name**: zh-programmer-document-guide
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-10-24
- **Last Updated**: 2024-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 程序员文档指南

### 前言

看到很多文章都声明"内容排版遵循xx风格指南", 感觉自己就像一个野路子一样

自己平时也确实会写些东西(记学习笔记而已), 别人的声明让我如鲠在喉, 一直在怀疑自己是不是特别low

故花费一些时间研究/实践xx风格指南, 结论是xx风格确实不适合我

在此把我的结论摆在这, 以飨后人

### 永远使用英文的半角标点符号

因为代码世界里都是英文的半角标点符号, 减少bug的出现, 解决中英混排的文档中来回切换中英标点符号的烦恼

> 写sql时, 是否因为单引号的错误使用无法运行
>
> 写js/java时, 是否因为分号的时候, 一直爆红

缺点

> 想打中文`书名号`打不出来, 那就放弃中文书名号吧
>
> 中文一句话打不出来`圆圈句号`, 那就接受, 习惯

总体来说, 利大于弊

### 中英文混写不需要增加空格

中文是方块字/象形字, 一字一意, 习惯中文的人潜意识获取信息时会一字一字读取

英文中, 单词是最小语义, 单词间是不得不加空格, 因为不加空格就无法识别每个单词了; 如果英文也是一个字母一个意思, 我敢保证英文不会形成加空格的形式

中英混写时, 两种语言区别明显, 故界限显而易见

> 当然, 你想写中间加空格, 我也不反对, 但这会增加心智成本

### 中文与数字之间不需要增加空格

理由同上, 中文和数字区别明显

> 当然, 中间加空格也OK.

### 逗号后要加个空格

根据上面的建议, 文字会挤到一块, 所以我们也有留白, 但这个留白是利用逗号/句点后的空格来实现的

> 英语习惯是一句话可以有好几十个词, 从句套从句, 而中文习惯是一个意群一个逗号, 而我们作为中文习惯的人, 还是建议多用逗号

建议: 若下句话是另起一行, 则本句结尾不加句点, 这样会让页面看的贼简洁, 贼舒服

### 参考

[中文技术文档的写作规范(阮一峰)](https://github.com/ruanyf/document-style-guide) 

[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)