July：咱们来简单讨论下排版格式、编码规范
julycoding opened this issue · 25 comments
大家可以各抒己见，针对排版格式，尤其是编码规范，有什么看法，最后达成共识，和一致的风格。
暂时用的格式：
一、关于空格
所有代码使用4个空格缩进
运算符后使用一个空格
"," 和for循环语句中的";" 后面跟上一个空格
条件、分支保留字，如 if for while else switch 后留出一个空格
"[]", "."和"->" 前后不留空格
用空行把大块代码分成逻辑上的“段落
C 指针中的指针符靠近类型名，如char* p;
二、关于标点
中文表述，使用全角的标点符号，如：（）、。，？
数学公式（包括文中混排的公式）和英文代码，使用半角的标点符号，如：(),.?…
关于注释
注释统一用中文
尽量用"//"，除非大段大段的注释，否则一般不用"/.../"
三、关于命名
类名为大写字母开头的单词组合
函数名以小写字母开头，后面紧跟的是大写字母开头的单词，比如maxSubArray
常量的命名都是大写字母的单词，之间用下划线隔开，比如MY_CONSTANT
变量尽量使用全名，能够描述所要实现的功能，如 highestTemprature；对于已经公认了的写法才使用缩写，如 tmp mid prev next
变量名能“望文生义”，如v1, v2不如area, height
il < 4384 和 inputLength < MAX_INPUT_LENGTH，后一种写法更好
四、一个函数只专注做一件事
12~15章标点符号中英文混淆
恩，标点符号的确需要统一下。该统一用英文标点，还是中文标点？
我觉得除了code都应该用中文标点符号
我提几个以前鄙司的文案规范，以作参考：
- 英文和中文，数字和字符之间留一个空格
- 用「」替代 “”
- 中英混排用中文符号
建议最好写一份详细地文案规范来让所有人遵守。
现在代码的编排各个语言的写法、命名、文件架构，包括注释的内容都感觉比较乱，觉着无从提交。需要统一一下格式，比如顶端定义一个包含注释的统一函数说明，放在同一个区域的某个解答代码并提供md中连接。
最近在学习latex，感觉使用latex排版会很漂亮、专业的；
我自己能力不足，只能说说了。
下午考完试我就准备调LaTeX模板了，有什么风格给example我来实现
@liuzheng712 ，赞，我一直在关注你弄那个SVM，工作量的确挺大，辛苦。
至于咱编程艺术，很多东西都没有现成的，先做了再说吧。
@Boshen 认为呢？
大家觉得需要统一什么风格的话提一个issue我们一起改，(比如python代码要符合python自己的规范)。
latex的话我暂时还没有什么意见， 风格我推荐artima出版的书的风格， 比如pdf: www.cs.ucsb.edu/~benh/260/Programming-in-Scala.pdf 网页版: http://www.artima.com/pins1ed/
Python就PEP8，工具用flake8 + pep8-naming就好吧。现在我看文章中C/C++代码中if等控制语句后的大括号是另起一行，倒是让我很是纠结。
C/C++不如就采用Codeblock里面的那个Astyle吧，就是大括号另起一行的那种写法。
然后编码建议采用UTF-8，要不然github的客户端会乱码的样子。
中文表述，使用全角的标点符号，如：（）、。，？
数学公式（包括文中混排的公式）和英文代码，使用半角的标点符号，如：(),.?…
看到一篇写得非常不错的11个代码规范，大家也可以看看：http://www.html5tricks.com/11-tips-to-coding-better.html 。
文中有一句话特别值得咱们学习：“一段通俗易懂的程序代码，应该是任何人只要看了代码，就能明白程序是用来干嘛的。”
摘录几点（尤其是最后一点，左大括号真的应该跟if在同一行么？）：
“1、尽可能让变量和方法的名称能够描述要实现的功能，比如n, ns, nsisd，和numTeamMembers, seatCount, numSeatsInStadium相比，后一种写法更好；
2、il < 4384 和 inputLength < MAX_INPUT_LENGTH，后一种写法更好；
3、方法名以小写字母开头，后面紧跟的是大写字母开头的单词，比如veryLongVariableName。
4、类名一般都是大写字母开头的单词组合。
5、常量的命名都是大写字母的单词，之间用下划线隔开，比如MY_CONSTANT
6、左大括号应该跟if在同一行（这点打个疑问..）”
编码规范里可以加上一条c里指针星号声明时的位置的规定。char * value vs char* value vs char *value .
恩，C 指针的声明以char* p; 为准。
注释为何不使用/*..../的形式呢
这个对于大段的解释还是挺有必要的
不需要是出于何种目的？
恩，大段的注释可以用/.../，但一般不会有大段大段的注释，都是比较短的，所以短的用//。
呵呵
于2014年5月29日 16:14:29,smartan写到:
注释为何不使用/*..../的形式呢
这个对于大段的解释还是挺有必要的
不需要是出于何种目的？—
Reply to this email directly or view it on GitHub
#81 (comment).
业界最高水平的早给过大家多次了，可以选取其中适用的子集
于2014年5月29日 16:42:16,fairywell28写到:
呵呵
于2014年5月29日 16:14:29,smartan写到:
注释为何不使用/*..../的形式呢
这个对于大段的解释还是挺有必要的
不需要是出于何种目的？—
Reply to this email directly or view it on GitHub
#81 (comment).
@fairywell28 ，Google c++ style 参看了，但也不会完全100% 遵照它的来。
@july
我当时是根据咱们的书的特点，总结的是一些适合我们的常见的子集（google+baidu+经验），其中还是有不少值得参考的。我觉得不用完全抛弃后找网上一些不怎么系统的、质量也不怎么高的。
于2014年5月29日 16:46:19,July写到:
@fairywell28 https://github.com/fairywell28 ，Google c++ style参看
了，但也不会完全100% 遵照它的来。—
Reply to this email directly or view it on GitHub
#81 (comment).
现在是 0% 的参照它来的
于2014年5月29日 16:46:19,July写到:
@fairywell28 https://github.com/fairywell28 ，Google c++ style参看
了，但也不会完全100% 遵照它的来。—
Reply to this email directly or view it on GitHub
#81 (comment).
@fairywell28
你觉得哪些点质量不高可以指出来啊
都是一条一条弄出来的，哪是从网上随便瞎找的
再者，我也不会一次性把所有规范一次性全部弄出来，都是边实践边总结的。
就算永远是0% 也无所谓，别人的东西再好也是别人的，关键要看是否合适自己，自己是否理解。
@july 你按自己的做吧
于 2014/5/29 16:58, July 写道:
@fairywell28 https://github.com/fairywell28
你觉得哪些点质量不高可以指出来啊
都是一条一条弄出来的，哪是从网上随便瞎找的再者，我也不会一次性把所有规范一次性全部弄出来，都是边实践边总结的。
—
Reply to this email directly or view it on GitHub
#81 (comment).
新书即将在今年2015年9月底上市。
感谢大家的共同努力。