軟件開發規范

一，為什么要規范軟件開發？

1.1 為什么要有規范軟件開發。

　　你現在包括之前寫的一些程序，所謂的'項目'，都是在一個py文件下完成的，代碼量撐死也就幾百行，你認為沒問題，挺好。但是真正的后端開發的項目，系統等，少則幾萬行代碼，多則十幾萬，幾十萬行代碼，你全都放在一個py文件中行么？當然你可以說，只要能實現功能即可。咱們舉個例子，如果你的衣物只有三四件，那么你隨便堆在櫥櫃里，沒問題，咋都能找到，也不顯得特別亂，但是如果你的衣物，有三四十件的時候，你在都堆在櫥櫃里，可想而知，你找你穿過三天的襪子，最終從你的大衣口袋里翻出來了，這是什么感覺和心情......

　　軟件開發，規范你的項目目錄結構，代碼規范，遵循PEP8規范等等，讓你更加清晰滴，合理滴開發。

　　軟件開發的首要規范就是從設計目錄結構開始。

1.2 為什么要設計項目目錄結構？

　"設計項目目錄結構"，就和"代碼編碼風格"一樣，屬於個人風格問題。對於這種風格上的規范，一直都存在兩種態度:

1. 一類同學認為，這種個人風格問題"無關緊要"。理由是能讓程序work就好，風格問題根本不是問題。
2. 另一類同學認為，規范化能更好的控制程序結構，讓程序具有更高的可讀性。

我是比較偏向於后者的，因為我是前一類同學思想行為下的直接受害者。我曾經維護過一個非常不好讀的項目，其實現的邏輯並不復雜，但是卻耗費了我非常長的時間去理解它想表達的意思。從此我個人對於提高項目可讀性、可維護性的要求就很高了。"項目目錄結構"其實也是屬於"可讀性和可維護性"的范疇，我們設計一個層次清晰的目錄結構，就是為了達到以下兩點:

1. 可讀性高: 不熟悉這個項目的代碼的人，一眼就能看懂目錄結構，知道程序啟動腳本是哪個，測試目錄在哪兒，配置文件在哪兒等等。從而非常快速的了解這個項目。
2. 可維護性高: 定義好組織規則后，維護者就能很明確地知道，新增的哪個文件和代碼應該放在什么目錄之下。這個好處是，隨着時間的推移，代碼/配置的規模增加，項目結構不會混亂，仍然能夠組織良好。

所以，我認為，保持一個層次清晰的目錄結構是有必要的。更何況組織一個良好的工程目錄，其實是一件很簡單的事兒。

二，較好的目錄結構方式（推薦）

 

具體分析：

#===============>start.py
# 開啟項目的start文件。
import sys,os
BASE_DIR=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.append(BASE_DIR)

from core import src

if __name__ == '__main__':
    src.run()
#===============>settings.py
# 配置文件，放一些路徑或者信息等配置
import os

BASE_DIR=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DB_PATH=os.path.join(BASE_DIR,'db','db.json')
LOG_PATH=os.path.join(BASE_DIR,'log','access.log')
LOGIN_TIMEOUT=5

"""
logging配置
"""
# 定義三種日志輸出格式
standard_format = '[%(asctime)s][%(threadName)s:%(thread)d][task_id:%(name)s][%(filename)s:%(lineno)d]' \
                  '[%(levelname)s][%(message)s]' #其中name為getlogger指定的名字
simple_format = '[%(levelname)s][%(asctime)s][%(filename)s:%(lineno)d]%(message)s'
id_simple_format = '[%(levelname)s][%(asctime)s] %(message)s'

# log配置字典
LOGGING_DIC = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'standard': {
            'format': standard_format
        },
        'simple': {
            'format': simple_format
        },
    },
    'filters': {},
    'handlers': {
        #打印到終端的日志
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',  # 打印到屏幕
            'formatter': 'simple'
        },
        #打印到文件的日志,收集info及以上的日志
        'default': {
            'level': 'DEBUG',
            'class': 'logging.handlers.RotatingFileHandler',  # 保存到文件
            'formatter': 'standard',
            'filename': LOG_PATH,  # 日志文件
            'maxBytes': 1024*1024*5,  # 日志大小 5M
            'backupCount': 5,
            'encoding': 'utf-8',  # 日志文件的編碼，再也不用擔心中文log亂碼了
        },
    },
    'loggers': {
        #logging.getLogger(__name__)拿到的logger配置
        '': {
            'handlers': ['default', 'console'],  # 這里把上面定義的兩個handler都加上，即log數據既寫入文件又打印到屏幕
            'level': 'DEBUG',
            'propagate': True,  # 向上（更高level的logger）傳遞
        },
    },
}


#===============>src.py
# 主要邏輯部分：
# 核心邏輯，代碼放在這。
from conf import settings
from lib import common
import time

logger=common.get_logger(__name__)

current_user={'user':None,'login_time':None,'timeout':int(settings.LOGIN_TIMEOUT)}
def auth(func):
    def wrapper(*args,**kwargs):
        if current_user['user']:
            interval=time.time()-current_user['login_time']
            if interval < current_user['timeout']:
                return func(*args,**kwargs)
        name = input('name>>: ')
        password = input('password>>: ')
        db=common.conn_db()
        if db.get(name):
            if password == db.get(name).get('password'):
                logger.info('登錄成功')
                current_user['user']=name
                current_user['login_time']=time.time()
                return func(*args,**kwargs)
        else:
            logger.error('用戶名不存在')

    return wrapper

@auth
def buy():
    print('buy...')

@auth
def run():

    print('''
購物
查看余額
轉賬
    ''')
    while True:
        choice = input('>>: ').strip()
        if not choice:continue
        if choice == '1':
            buy()



#===============>db.json
# 重要數據放在這里

#===============>common.py
# 公共組件放在這里：公共功能部分。
from conf import settings
import logging
import logging.config
import json

def get_logger(name):
    logging.config.dictConfig(settings.LOGGING_DIC)  # 導入上面定義的logging配置
    logger = logging.getLogger(name)  # 生成一個log實例
    return logger


def conn_db():
    db_path=settings.DB_PATH
    dic=json.load(open(db_path,'r',encoding='utf-8'))
    return dic


#===============>access.log
# 日志信息
[2017-10-21 19:08:20,285][MainThread:10900][task_id:core.src][src.py:19][INFO][登錄成功]
[2017-10-21 19:08:32,206][MainThread:10900][task_id:core.src][src.py:19][INFO][登錄成功]
[2017-10-21 19:08:37,166][MainThread:10900][task_id:core.src][src.py:24][ERROR][用戶名不存在]
[2017-10-21 19:08:39,535][MainThread:10900][task_id:core.src][src.py:24][ERROR][用戶名不存在]
[2017-10-21 19:08:40,797][MainThread:10900][task_id:core.src][src.py:24][ERROR][用戶名不存在]
[2017-10-21 19:08:47,093][MainThread:10900][task_id:core.src][src.py:24][ERROR][用戶名不存在]
[2017-10-21 19:09:01,997][MainThread:10900][task_id:core.src][src.py:19][INFO][登錄成功]
[2017-10-21 19:09:05,781][MainThread:10900][task_id:core.src][src.py:24][ERROR][用戶名不存在]
[2017-10-21 19:09:29,878][MainThread:8812][task_id:core.src][src.py:19][INFO][登錄成功]
[2017-10-21 19:09:54,117][MainThread:9884][task_id:core.src][src.py:19][INFO][登錄成功]

關於README的內容

這個我覺得是每個項目都應該有的一個文件，目的是能簡要描述該項目的信息，讓讀者快速了解這個項目。

它需要說明以下幾個事項:

1. 軟件定位，軟件的基本功能。
2. 運行代碼的方法: 安裝環境、啟動命令等。
3. 簡要的使用說明。
4. 代碼目錄結構說明，更詳細點可以說明軟件的基本原理。
5. 常見問題說明。

我覺得有以上幾點是比較好的一個README。在軟件開發初期，由於開發過程中以上內容可能不明確或者發生變化，並不是一定要在一開始就將所有信息都補全。但是在項目完結的時候，是需要撰寫這樣的一個文檔的。

可以參考Redis源碼中Readme的寫法，這里面簡潔但是清晰的描述了Redis功能和源碼結構。