My practice is a machine learning-related, so I chose the following source code to learn on GitHub: https://github.com/WillKoehrsen/machine-learning-project-walkthrough
An analysis of the source code
1, the directory structure
The source code uses the Python language, written on jupyter notebook. There is a file in the directory uto_ml, Data, deprecated, Images four folders and Machine Learning Project Part 1.ipynb, Machine Learning Project Part 2.ipynb, Machine Learning Project Part 3.ipynb like source code file, wherein:
Auto_ml folder is stored in the pipeline programs;
Data stored in the folder of the project is the training and test sets and other compressed data packet;
Deprecated folders stored in the file is a program for data exploration;
Folder images are stored in image files used in the project.
2, code style
Because the project does not use a class, not discussed issues related to all classes. We randomly selected in the source code for some functions to achieve code.
- Part of the code of the different functions are separated by a blank line, and the comment sentence have a front section of the functions described in lucid;
- Naming variables and functions used in English spelling and English half fight + spaced underlined combinations readily understand the meaning of the expression or function of the variable. But the name does not recommend using Python language hump naming, though still clear, but it is recommended that instead hump naming;
- And use spaces to indent the code are in line with Python norms;
- Since Jupyter Notebook unique code block edit mode, you can insert comments illustrative blocks of code, such code context will more clearly shown below:
3, suggestions for improvement:
- As shown in FIG. 9th line of code, a two row write code, which is non-standard behavior, a proposal to change each line of code;
- 还有第2部分所描述的变量命名改为驼峰命名方式。
二、总结同类编程语言或项目在代码规范和风格的一般要求
通过对源代码的学习以及相关资料的查阅，下面对python语言的规范和风格做一下总结：
1、注释的使用
- 注释的使用在编程中非常重要，因为代码不仅仅是拿来给机器运行的，还是给自己或者别人看的；
- 要用英文写注释；
- 如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符；
- 在修改代码的时候一定要同步更改注释，代码与注释矛盾会给阅读代码带来很大的困扰；
- 尽量使用块注释，少使用行注释；
- 避免没有必要的注释。
2、缩进
- 整齐的缩进会使得代码条理清楚，整洁易读；
- 空格是首选的缩进方式，制表符只能用于与同样使用制表符缩进的代码保持一致，Python3不允许同时使用空格和制表符的缩进；
- 每一级缩进使用4个空格。
- 续行应该与其包裹元素对齐，要么使用圆括号、方括号和花括号内的隐式行连接来垂直对齐，要么使用挂行缩进对齐；
- 当使用挂行缩进时，应该考虑到第一行不应该有参数，以及使用缩进以区分自己是续行；
- 每行最大长度79，换行可以使用反斜杠，最好使用圆括号，换行点要在操作符的后边敲回车。
3、空格的使用
- 各种右括号前不要加空格；
- 逗号、冒号、分号前不要加空格；
- 函数的左括号前不要加空格。如Func(1)；
- 序列的左括号前不要加空格。如list[2]；
- 操作符左右各加一个空格，不要为了对齐增加空格；
- 函数默认参数的赋值符左右省略空格；
- 不要将多句语句写在同一行，尽管使用‘；’允许；
- if/for/while语句中，即使执行语句只有一句，也必须另起一行。
4、命名规范
- 那些暴露给用户的API接口的命名，应该遵循反映使用场景而不是实现的原则
- 永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。在有些字体里，这些字符无法和数字0和1区分，如果想用‘l’，用‘L’代替；
- 模块应该用简短全小写的名字，如果为了提升可读性，可以用下划线；
- 包命名尽量短小，使用全部小写的方式，不可以使用下划线；
- 类名一般使用首字母大写的约定。在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字母大写的命名法只用于异常名或者内部的常量；
- 类的属性（方法和变量）命名使用全部小写的方式，可以使用下划线；
- 因为异常一般都是类，所有类的命名方法也适用于异常。然而需要在异常名后面加上“Error”后缀（如果异常确实是一个错误）；
- 函数名应该小写，如果想提高可读性可以用下划线分隔；
- 始终要将 self 作为实例方法的的第一个参数。始终要将 cls 作为类静态方法的第一个参数；
- 常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 NUM。