分拆程序、提供文档

1.为什么要分拆程序，大家不能只在Shell中工作，分拆程序会使得代码更容易复用，也容易保存。
尽量把类和函数分拆成最可能复用的代码段。
2.通过文件目录包含模块。
如果模块和运行的文件在相同的目录下，就很容易包含它。假设有一个叫做books.py的模块，并且包容了Book类，如果想在自己的程序中包含Book，文件的开头：from books import Book
如果这个文件不在一个目录中，就不能这么做，必须加上文件的目录。
查看当前路径,在Shell中输入如下命令

>>> import sys
>>> for directory in sys.path:
	print(directory)

Python先要在“我的电脑”中查找所有目录。为了告诉Python想要将目录下的一个文件夹当作包一样使用，需要添加 一个文件__init__.py，通常，__init__.py是空的，其目的就是告诉Python，我们想要使用该目录的代码，如果一个文件夹中没有此文件，Python就知道要忽略这个目录

3.导入模块
一旦Python在正确的目录下找到相应的模块，就可以导入它们，假设有mon.py模块，在classes文件夹下，其中有一个mon类，导入这个类：
from classes.mon import mon，模块名与文件名是一样的，但是模块名末尾没有.py，句点位于文件夹和模块名称之间。
如果在文件夹名或是文件名中使用了中划线（-）Python在导入模块时会有问题，可以用下划线来代替中划线。
注意：必须先修改路径，再导入mon，否则，程序会报错，并且程序不会运行到修改路径的那个地方。
4.os.getcwd()返回运行脚本的目录，而不是脚本所在的目录。
Python会查看所有包含在Python路径下的文件夹中查找要导入的模块，如果没有找到和import语句匹配的模块，会返回错误。

 

提供文档
文档在将来可能还会对我们有所帮助。
好的文档应该告诉用户想要使用一段代码所需要知道的信息，而且没有废话。
好的文档应该是有组织的。

1.在代码中嵌入注释
在开头放置#字符
在下面这些情况下，添加注释是一个好主意
  1>有一个细微的需求，不想让另一个程序 员更改它
  2>代码中有一个等式，其他人可能不理解它
  3>对于一个代码 块所做的事情，想要给出一个一般性的概括。
注释对于程序中需要临时删除的代码也很有用。

2.用docstring说明代码
docstring是一种特殊类型的注释，可以把它放在一个函数或类定义之后，或者放在一个文件的开头。通常，它位的角色是说明函数、类或模块是做什么的。
docstring可以用三引号、单引号或双引号括起来
docstring有一些内建的函数，它们使用docstring来帮助其他程序员使用你的代码。

>>> class Test(object):
	'''this is just a test object.
           It doesn't do much,really.
        '''
	def __init__(self):
		'''This sets up the test object.
                   Doesn't take any parameters.
                '''
		self.num=10

		
>>> t=Test()
>>> help(t)
Help on Test in module __main__ object:

class Test(builtins.object)
 |  this is just a test object.
 |  It doesn't do much,really.
 |  
 |  Methods defined here:
 |  
 |  __init__(self)
 |      This sets up the test object.
 |      Doesn't take any parameters.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

一些适合包含在docstring中的内容
1>函数或类是干什么的
2>类是否可以直接使用，或者它只是基类，不能够单独使用。
3>用户期望从一个函数中返回什么
4>可能要给出的任何警告
5>参数中的值应该是什么数据类型
PEP 257包含了编写docstring的指南。可以浏览“http://www.python.org/dev/peps/pep-0257”以阅读这些指南。

3.包含README文件和安装文件
README文件应该包含的一些内容
1>代码要在哪个Python版本下运行
2>代码是做什么的
3>如何安装代码
4>代码需要的哪些库不在标准库中
README文件应该总是保存为文本文件。
README文件应该和main.py在同一级目录中，有时README文件过长或者安装说明复杂，可以把安装说明分割成一个单独的文件，通常这个文件叫INSTALL.txt，它也保存在根目录下。
根目录是什么？
它就是我们所谈及的任何目录结构的最底层目录。
INSTALL文件可能要包含的一些内容
1>程序所需的任何其他的库
2>如何安装你的代码（如果需要的话）
3>如何运行你的代码（如果需要的话）

编写README文件
README文件没有固定的格式，但是应该从最重要的项开始：代码使用Python的哪个版本？要让程序运行还需要用户安装什么？以及这个程序的作用是什么？
在介绍完重要信息以后，可能还需要考虑一些其他的信息
1>包含所有最近更改的changelog
2>程序中应该包含的所有文件的列表（这有助于人们搞清楚为什么有些内容不工作）
3>向那些对程序提供帮助的人致谢
4>联系信息（如果你想让将来的用户能够找到你）

不必为每行代码都添加注释（除非它是极为复杂的代码），描述代码的docstring也不应该超过代码长度的3倍以上。
我们应该避免使用像Word这样的字处理程序来编写文档文件，因为不能通过命令行阅读Word文件，要阅读Word文件，需要 一个特殊的程序，并不是每个人都想安装这样一个程序。