优美胜于丑陋 明了胜于晦涩 简洁胜于复杂 复杂胜于凌乱 扁平胜于嵌套 间隔胜于紧凑 可读性很重要 即便假借特例的实用性之名,也不可违背这些规则
上面是 Python 之禅,很好地体现了 Python 语言所传达的编程理念。
PEP8 规范: https://www.python.org/dev/peps/pep-0008/
标准:
__all__
, __author__
, __version__
等这样的模块级“呆名“(也就是名字里有两个前缀下划线和两个后缀下划线),应该放在文档字符串的后面,以及除 from __future__
之外的import
表达式前面。Python要求将来在模块中的导入,必须出现在除文档字符串之外的其他代码之前。
"""This is the example module. This module does stuff. """ from __future__ import barry_as_FLUFL __all__ = ['a', 'b', 'c'] __version__ = '0.1' __author__ = 'Cardinal Biggles' import os import sys (1)模块应该用简短全小写的名字,如果为了提升可读性,下划线也是可以用的。Python包名也应该使用简短全小写的名字,但不建议用下划线。
(2)类名一般使用首字母大写的约定。
在接口被文档化并且主要被用于调用的情况下,可以使用函数的命名风格代替。
注意,对于内置的变量命名有一个单独的约定:大部分内置变量是单个单词(或者两个单词连接在一起),首字母大写的命名法只用于异常名或者内部的常量。
(3)因为异常一般都是类,所有类的命名方法在这里也适用。然而,你需要在异常名后面加上“Error”后缀。
(4)函数名应该小写,如果想提高可读性可以用下划线分隔。
(5)全局变量名和函数命名规则一样,值得注意的是通过 from M import *
导入的模块应该使用all机制去防止内部的接口对外暴露,或者使用在全局变量前加下划线的方式。
(6)如果函数的参数名和已有的关键词冲突,在最后加单一下划线比缩写或随意拼写更好。
(7)常量通常定义在模块级,通过下划线分隔的全大写字母命名。例如: MAX_OVERFLOW
和 TOTAL
。
SystemExit
和KeyboardInterrupt
异常,这样会很难通过ctrl+C中断程序,而且会掩盖掉其他问题。如果你想捕获所有指示程序出错的异常,使用 except Exception
。
正确的是:
try: import platform_specific_module except ImportError: platform_specific_module = None 具体的可以使用Autopep8工具协助排版。
安装autopep8:
pip install autopep8
用法:
autopep8 [参数] [Python文件]
核心参数:
-d, --diff print the diff for the fixed source
-i, --in-place make changes to files in place
--global-config filename
path to a global pep8 config file; if this file does
not exist then this is ignored (default:
~/.config/pep8)
--ignore-local-config
don't look for and apply local config files; if not
passed, defaults are updated with any config files in
the project's root directory
-r, --recursive run recursively over directories; must be used with
--in-place or --diff
-j n, --jobs n number of parallel jobs; match CPU count if value is
less than 1
-p n, --pep8-passes n
maximum number of additional pep8 passes (default:
infinite)
-a, --aggressive enable non-whitespace changes; multiple -a result in
more aggressive changes
--experimental enable experimental fixes
--exclude globs exclude file/directory names that match these comma-
separated globs
--list-fixes list codes for fixes; used by --ignore and --select
--ignore errors do not fix these errors/warnings (default:
E226,E24,W50,W690)
--select errors fix only these errors/warnings (e.g. E4,W)
--max-line-length n set maximum allowed line length (default: 79)
--line-range line line, --range line line
only fix errors found within this inclusive range of
line numbers (e.g. 1 99); line numbers are indexed at
1
--hang-closing hang-closing option passed to pycodestyle
--exit-code change to behavior of exit code. default behavior of
return value, 0 is no differences, 1 is error exit.
return 2 when add this option. 2 is exists
differences.
--in-place
会直接将结果保存到源文件中,如果不包含--in-place
选项,则会将autopep8格式化以后的代码直接输出到控制台。
Go 代码审核规范官方地址: https://github.com/golang/go/wiki/CodeReviewComments
/**/
,C++的行注释风格//
。包注释必须出现在 package 声明的临近位置,无空行。所有的顶级导出的名称都应该有 doc 注释,重要的未导出类型或函数声明也应如此。每个public函数都应该有注释,注释句子应该以该函数名开头,如:
// Compile parses a regular expression and returns, if successful, // a Regexp that can be used to match against text. func Compile(str string) (*Regexp, error) {} fmt.Errorf("something bad")
而不要使用fmt.Errorf("Something bad")
,因此log.Printf("Reading %s: %v", filename, err)
的格式中将不会出现额外的大写字母。否则这将不适用于日志记录,因为它是隐式的面向行,而不是在其他消息中组合。
_test.go
文件中,比如:
package stringutil_test import ( "fmt" "github.com/golang/example/stringutil" ) func ExampleReverse() { fmt.Println(stringutil.Reverse("hello")) // Output: olleh } 这种写法的好处是使用 go test -v
,如果和注释种的结果一致只会返回PASS
,如果不一定打印。
_
变量丢弃 error 如果函数返回 error,请检查它以确保函数成功。处理 error,返回 error,或者在真正特殊的情况下使用 panic。
.
形式导入它们:
package foo_test import ( "bar/testutil" // also imports "foo" . "foo" ) 正确的生产者应该这样实现:
package producer
type Thinger struct{ … }
func (t Thinger) Thing() bool { … }
func NewThinger() Thinger { return Thinger{ … } }
// 而不是在这里再声明一个接口,这样是没必要的
// type Thinger interface { Thing() bool }
// type defaultThinger struct{ … }
// func (t defaultThinger) Thing() bool { … }
// func NewThinger() Thinger { return defaultThinger{ … } }
go 的官方工具链做得很好,可以直接使用gofmt
和golint
检查代码规范。
安装:
go get github.com/golang/lint
go install github.com/golang/lint
用法:
golint <文件/文件目录/包名>