登陆注册
71628900000012

第12章 编码风格和文档化工作

程序的建立要做到容易阅读,也容易理解。在这一个标准上,好的程序员在脑子里都是首先在乎他们的编码风格。开发这样一种代码风格是为了达到既可以让人,也可以让电脑保持良好地沟通,尤其是在程序的设计方面尤为重要。

当然有许多不同的编码风格,对于 Python 来说,官方标准就是 PEP8 这份文档了。你们可以自行查看官方文献来了解细节,我挑选主要的几项来介绍一下:

第一:

Python 代码块通常都是用 4 个空格来形成缩进句法。高度重视不要把空格与 Tab 制表符混用,因为不同的系统对待处理制表符时采用的宽度不一样,并且 Python 解释器不会把 Tab 和空格看成一个对象。许多纯文本编辑器都具有自动把 Tab 键转换成空格形式的功能。

第二:

使用顾名思义的识别符命名法。在选择用什么名字的时候,要能够让人读的出来,名字也能反映出行为、责任、或数据的含义。其中包括了:

类的名字( Python 的内置类型名也是如此)使用名词单数形式,首字母要大写。如果使用了多个单词的话,我们会遵循 CamelCase 驼峰体样式来书写类名,也就是每个单词的首字母都要大写,并紧紧相连,不需要使用下划线作为连接符。

函数的名字( Python 的内置函数名也是一样的)也涉及一个类里定义方法的名字,它们都采用全小写形式。如果使用多个单词,使用单个下划线来做连接点。函数的名字通常使用动词,这样才反映出函数或方法是做什么的。当然这里也有一种情况就是,如果你的函数或方法只是负责返回一个值,那么可以使用名词起名。

名字都是用来识别单个对象的,就是说要避免重名的现象,否则会出现歧义。例如,参数名、实例变量名、本地变量名,都采用全小写名词来命名。当然也会有用单个大写字母来命名的,例如一个数据结构的命名采用了 T 来说明是一种树状结构。

识别符有许多,其中有用来表示一种常量值,这也是一种传统用法,采用了全大写与单个下划线组合形式,这样的名字意味着是一种常量。

在命名的时候也会看到使用下划线作为名字的开头部分,这种命名风格会体现在封装识别符中,如此一来以单下划线开始的名字会作为一个类或一个模块的内部用法,而不会默认作为公开接口的组成部分。

第三:

在写代码时可以使用#井号来些代码中的注释内容,从而提升代码中歧义或不明白现象的解释。

注释的内容可以使用单行注释,也可以多行注释,这就根据你要说的话多少来自有裁决。

多行注释依然使用的是#号字符,而不是多行字符串。有一些代码中常会使用多行字符串来写多行注释,这样不是一个好的习惯。下面会介绍一下多行字符串的文档化功用。

文档化工作中,Python 提供了集成支持,意思就是可以直接在源代码中书写文档化内容,这种机制就叫做“文档字符串”。采用的是三引号对儿句法,这样可以书写多行文本内容,主要使用在如下三个地方:

第一个文档化:模块文档

当文档字符串作为模块的第一个语句时,会称为模块的帮助文档内容。书写文档字符串的格式是,第一行会作为总结性的标题内容,然后增加一个空行,接着新起一行来写详细的内容。

第二个文档化:函数文档

第三个文档化:类的文档和方法的文档

文档字符串的内容会可以直接被 Python 中的 help()内置函数引用,现在你们知道帮助文档的内容来自哪里了吧。文档字符串的官方标准是 PEP257 文献,当然也有一些文档化工具,这里我们就不介绍了。

同类推荐
  • 末世生存我要先做个梦

    末世生存我要先做个梦

    许楠本是一个将要面临高考的高中生,做了一个噩梦,告诉许楠末世将要降临,逃命吧!胖子:小南,丧尸要来了!什么,你要睡个觉先?
  • 快穿:戏精互怼日常

    快穿:戏精互怼日常

    清瞳任务失败莫名其妙死亡后绑定了一个系统,然后穿越各个世界,完成寄体的遗愿,顺便给某狗系统收集情绪值。某狗系统:宿主!放下你手中的危险物品!清瞳:你说什么?风太大我听不清啊!某男:媳妇加油!我支持你!
  • 人族不灭

    人族不灭

    全球一夜之间,发生了巨大灾变,人类赖以生存的电力无法在使用了,人类文明一下子从信息时代,变成了蒸汽时代,生产力大幅度下降。面对70亿的人口,各种资源应付相形见拙,地球村也不再是地球村。交通、通讯工具落后的隔离,使得地域分化也日益显著。以此同时人类也遭到外来种族的入侵.........
  • 末世重生:女王陛下万岁

    末世重生:女王陛下万岁

    新世纪30年,旧历2036年,末世第一安全区区长唐果去世,享年40岁。全国人民为其默哀,所有安全区旗帜皆降落。她的死,载入了末世历史中,堪称末世之后发生的最大的一起事件,短短一天希望安全区内发生了五起暴动。
  • 星际之十日横空

    星际之十日横空

    当银河系出现十个太阳会发生怎样的事情星际时代,人类已经掌握了强大的科技力量,面对十个太阳他们会如何选择?是用他们的科技武器如同后羿射日一般将这十个太阳一个个的轰下来?还是合理运用它们带来的能源呢?如果这些太阳有意识呢?这是一个人类逐渐化身为太阳的故事,洪荒三足金乌在星际复活了......
热门推荐
  • 鞘奴

    鞘奴

    一个身负奇怪剑鞘的异人和他新同伴们的故事。
  • 魔尊图腾

    魔尊图腾

    少年天骄,被同门陷害,一剑穿身时,誓言:愿,没有来生,愿,成魔,报仇雪恨!我既为魔,举世皆魔!
  • 恶魔校草:丫头,让我乖乖宠

    恶魔校草:丫头,让我乖乖宠

    初入校园,凌雪琪就被那个臭恶魔校草给抢走了初吻。再次见面,再次被夺走吻,又被夺走了呼吸!死恶魔吻完又说:“味道不错!”又一次扬长而去!第三次,她被他壁咚在床上,她总算忍不住了“死恶魔,你属狗的吗?好疼!”“这样别人才会记住你是我楠宫阡的女人。”小丫头,你就听话点,要不然我会有很多的方法的,要不要试一试?”“果然是超级大变态。”可是,每次别的女生对他这样,为什么自己这么难过呢?
  • 我只要你喜欢我

    我只要你喜欢我

    那一天,我做了一件错事,给我喜欢的学长写了一封情书,结果失败了,而且学长那高高在上的样子,令我讨厌!更加疯狂的是,这件事情还轰动了整个学校...之后,学长说了一句话,却让我再一次让我陷入其中,那就是...我只要你喜欢我,就仅此而已!这是一场早已算计好的阴谋,我身陷其中,无法自拔,或许这就是,当局者迷的哀痛吧...原来,我早在很久以前,就离开了这个世界...不过呢,谢谢你还记得我,真是感激不尽!(封面制作感谢小黑)我不是专业小说家,也不能像女频作者那样写的如此细腻,我就是一个普通人,简简单单写写心里想表达的故事,这就是我写这本小说的用意,谢谢大家喜欢,感激不尽!
  • 热血钦差

    热血钦差

    现代混混穿越大清后偶遇钦差被白莲教杀死,发现自己与其一摸一样,混混欣然接受了钦差的一切,在大清官场争权夺利,举兵起义,逍遥非常…
  • 瀚海之飞雪漫天

    瀚海之飞雪漫天

    瀚海,一把杀人不见血的剑......瀚海,一段认人怆然涕下,无限感概的往事......
  • 与风有云

    与风有云

    甜文,作者新手小白逗比更新不定。萧瑜曾经的一切被打破后重新回复原点,她想了。又与没想一样,胡乱地走下去。有人为之保驾护航,有人乱闯。(重生文)没有金手指。
  • A Kidnapped Santa Claus

    A Kidnapped Santa Claus

    本书为公版书,为不受著作权法限制的作家、艺术家及其它人士发布的作品,供广大读者阅读交流。
  • 妃常累之转眼即是万年

    妃常累之转眼即是万年

    她,是恶搞公主,他是恶魔王爷。当他们在一次偶然中相遇是巧合还是命中注定呢....................
  • 天行

    天行

    号称“北辰骑神”的天才玩家以自创的“牧马冲锋流”战术击败了国服第一弓手北冥雪,被誉为天纵战榜第一骑士的他,却受到小人排挤,最终离开了效力已久的银狐俱乐部。是沉沦,还是再次崛起?恰逢其时,月恒集团第四款游戏“天行”正式上线,虚拟世界再起风云!