程序员文档指南

前言

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

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

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

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

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

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

写sql时, 是否因为单引号的错误使用无法运行

写js/java时, 是否因为分号的时候, 一直爆红

缺点

想打中文书名号打不出来, 那就放弃中文书名号吧

中文一句话打不出来圆圈句号, 那就接受, 习惯

总体来说, 利大于弊

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

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

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

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

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

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

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

当然, 中间加空格也OK.

逗号后要加个空格

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

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

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

参考

中文技术文档的写作规范(阮一峰)

中文文案排版指北