julycoding/The-Art-Of-Programming-By-July-2nd

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都应该用中文标点符号

我提几个以前鄙司的文案规范,以作参考:

  1. 英文和中文,数字和字符之间留一个空格
  2. 用「」替代 “”
  3. 中英混排用中文符号

建议最好写一份详细地文案规范来让所有人遵守。

现在代码的编排各个语言的写法、命名、文件架构,包括注释的内容都感觉比较乱,觉着无从提交。需要统一一下格式,比如顶端定义一个包含注释的统一函数说明,放在同一个区域的某个解答代码并提供md中连接。

wz12 commented

最近在学习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月底上市。
感谢大家的共同努力。