Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

July:咱们来简单讨论下排版格式、编码规范 #81

Closed
julycoding opened this issue Jan 1, 2014 · 25 comments
Closed

July:咱们来简单讨论下排版格式、编码规范 #81

julycoding opened this issue Jan 1, 2014 · 25 comments

Comments

@julycoding
Copy link
Owner

大家可以各抒己见,针对排版格式,尤其是编码规范,有什么看法,最后达成共识,和一致的风格。

暂时用的格式:
一、关于空格
所有代码使用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,后一种写法更好

四、一个函数只专注做一件事

@yansha87
Copy link
Contributor

yansha87 commented Jan 1, 2014

12~15章标点符号中英文混淆

@julycoding
Copy link
Owner Author

恩,标点符号的确需要统一下。该统一用英文标点,还是中文标点?

@yansha87
Copy link
Contributor

yansha87 commented Jan 1, 2014

我觉得除了code都应该用中文标点符号

@baurine
Copy link

baurine commented Jan 4, 2014

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

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

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

@jasonwbw
Copy link
Contributor

jasonwbw commented Jan 4, 2014

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

@wz12
Copy link

wz12 commented Jan 5, 2014

最近在学习latex,感觉使用latex排版会很漂亮、专业的;
我自己能力不足,只能说说了。

@liuzheng
Copy link
Contributor

liuzheng commented Jan 6, 2014

下午考完试我就准备调LaTeX模板了,有什么风格给example我来实现

@julycoding
Copy link
Owner Author

@liuzheng712 ,赞,我一直在关注你弄那个SVM,工作量的确挺大,辛苦。
至于咱编程艺术,很多东西都没有现成的,先做了再说吧。

@Boshen 认为呢?

@Boshen
Copy link
Collaborator

Boshen commented Jan 6, 2014

大家觉得需要统一什么风格的话提一个issue我们一起改,(比如python代码要符合python自己的规范)。

latex的话我暂时还没有什么意见, 风格我推荐artima出版的书的风格, 比如pdf: www.cs.ucsb.edu/~benh/260/Programming-in-Scala.pdf 网页版: http://www.artima.com/pins1ed/

@schemacs
Copy link
Contributor

Python就PEP8,工具用flake8 + pep8-naming就好吧。现在我看文章中C/C++代码中if等控制语句后的大括号是另起一行,倒是让我很是纠结。

@Xuanwo
Copy link
Contributor

Xuanwo commented Jan 20, 2014

C/C++不如就采用Codeblock里面的那个Astyle吧,就是大括号另起一行的那种写法。
然后编码建议采用UTF-8,要不然github的客户端会乱码的样子。

@julycoding
Copy link
Owner Author

中文表述,使用全角的标点符号,如:()、。,?
数学公式(包括文中混排的公式)和英文代码,使用半角的标点符号,如:(),.?…

@julycoding
Copy link
Owner Author

看到一篇写得非常不错的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在同一行(这点打个疑问..)”

@wolflee
Copy link

wolflee commented May 28, 2014

编码规范里可以加上一条c里指针星号声明时的位置的规定。char * value vs char* value vs char *value .

@julycoding
Copy link
Owner Author

恩,C 指针的声明以char* p; 为准。

@edisonan
Copy link

注释为何不使用/*..../的形式呢
这个对于大段的解释还是挺有必要的
不需要是出于何种目的?

@julycoding
Copy link
Owner Author

恩,大段的注释可以用/.../,但一般不会有大段大段的注释,都是比较短的,所以短的用//。

@fairywell28
Copy link

呵呵

于2014年5月29日 16:14:29,smartan写到:

注释为何不使用/*..../的形式呢
这个对于大段的解释还是挺有必要的
不需要是出于何种目的?


Reply to this email directly or view it on GitHub
#81 (comment).

@fairywell28
Copy link

业界最高水平的早给过大家多次了,可以选取其中适用的子集

于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).

@julycoding
Copy link
Owner Author

@fairywell28 ,Google c++ style 参看了,但也不会完全100% 遵照它的来。

@fairywell28
Copy link

@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).

@fairywell28
Copy link

现在是 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).

@julycoding
Copy link
Owner Author

@fairywell28
你觉得哪些点质量不高可以指出来啊
都是一条一条弄出来的,哪是从网上随便瞎找的

再者,我也不会一次性把所有规范一次性全部弄出来,都是边实践边总结的。
就算永远是0% 也无所谓,别人的东西再好也是别人的,关键要看是否合适自己,自己是否理解。

@fairywell28
Copy link

@july 你按自己的做吧

于 2014/5/29 16:58, July 写道:

@fairywell28 https://github.com/fairywell28
你觉得哪些点质量不高可以指出来啊
都是一条一条弄出来的,哪是从网上随便瞎找的

再者,我也不会一次性把所有规范一次性全部弄出来,都是边实践边总结的。


Reply to this email directly or view it on GitHub
#81 (comment).

@julycoding
Copy link
Owner Author

新书即将在今年2015年9月底上市。
感谢大家的共同努力。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests