javascript項目開發規範實例

首次發表在我的博客

總結一下我的在開發及review同事代碼的過程當中遇到的由於一些項目規範帶來的問題及認爲比較好的解決方法;
因爲我的經驗和認知水平有限,下面僅表明個人我的觀念,歡迎各位大佬多給我提建議;

以本人最近寫的一個項目(技術棧爲Meteor + React + MongoDB)爲例

readme的使用

由於一個項目每每須要不少人一塊兒協助開發,還有可能會不斷有新手接手項目,因此readme裏面必定要僅可能多的信息

• 項目啓動命令

• 代碼規範

  • Commit Message 編寫規範
  • 命名: class命名,變量命名,函數命名,組件命名等
• 組件
• 目錄結構
• 常遇到的問題及解決方案

也能夠加一些項目中遇到的設計到的文檔連接

代碼規範

Commit Message 編寫規範

編寫Commit Message須要遵循必定的範式，內容應該清晰明瞭，指明本次提交的目的，便於往後追蹤問題。

feat: 新功能
fix: 修補bug
docs: 文檔
style: 格式(不影響代碼運行的變更)
refactor: 重構
test: 添加測試
chore: 構建過程或輔助工具的變更

命名

命名的語義化真的特別特別重要,哪怕不知道要命名的這個詞的英文是什麼,也要去查一下;千萬不要以a,b,c等沒有任何語義的詞去命名;以前我也老是注意不到這一點,可是最近在看同事的代碼還有重構本身以前寫的部分代碼,命名壓根看不明白這個變量的意思,總之,看這樣的代碼怎一個痛苦了得

常見class命名關鍵詞：
佈局類：header, footer, container, main, content, aside, page, section
包裹類：wrap, inner
區塊類：region, block, box
結構類：hd, bd, ft, top, bottom, left, right, middle, col, row, grid, span
列表類：list, item, field
主次類：primary, secondary, sub, minor
大小類：s, m, l, xl, large, small
狀態類：active, current, checked, hover, fail, success, warn, error, on, off
導航類：nav, prev, next, breadcrumb, forward, back, indicator, paging, first, last
交互類：tips, alert, modal, pop, panel, tabs, accordion, slide, scroll, overlay,
星級類：rate, star
分割類：group, seperate, divider
等分類：full, half, third, quarter
表格類：table, tr, td, cell, row
圖片類：img, thumbnail, original, album, gallery
語言類：cn, en
論壇類：forum, bbs, topic, post
方向類：up, down, left, right
其餘語義類：btn, close, ok, cancel, switch; link, title, info, intro, more, icon; form, label, search, contact, phone, date, email, user; view, loading...

變量命名: 名字要能準確的描述出該變量所表明的事物
好比表示user的id就叫userId,而不要只叫user

函數命名建議：可以使用常見動詞約定

動詞       含義      
 get       獲取某個值            
 set       設置某個值             
 is        判斷是否爲某個值    
 has       判斷是否有某個值

如下規則是此項目中使用的,主要看團隊代碼習慣:

1. 組件名和組件所在文件名使用大駝峯式
2. css類名使用小寫單詞並用橫線(-)分割
3. dom節點以$開頭

組件

1. 每一個組件佔一個文件
2. 組件不包含狀態則應寫爲 stateless 組件
3. 非 stateless 組件使用 pure-render-decorator 優化

目錄結構

├── client  
│   ├── main.html                       客戶端頁面模板
│   └── main.js                         客戶端入口  
├── imports  
│   ├── client  
│   │   ├── App.jsx                     頂層組件  
│   │   ├── components                  公共組件  
│   │   ├── routers                     前端路由  
│   │   ├── styles                      樣式  
│   │   └── views                       視圖  
│   │       ├── header                  公共頭  
│   │       ├── login                   登陸註冊  
│   ├── schema                          模型  
│   └── util                            工具函數  
├── packages                            自定義 meteor 包  
├── public                              客戶端資源  
└── server   
    ├── main.js                         服務端入口  
    └── user                            用戶接口

issues的使用

項目中總會遇到不少奇奇怪怪的問題,當時印象深入,過了一段時間,就忘了具體的問題及解決辦法,雖然每次能夠經過查commit爲fix的記錄,可是這樣查找起來很麻煩,咱們項目是用gitlab來託管,能夠合理的理由issues,每次遇到很棘手的問題的時候,能夠提一個issues,等後期把這個問題解決了再把這個issues給關閉,並寫上問題緣由及解決辦法分析

下面補充的是項目中針對Meteor後端開發的一些規範

數據庫

Collection 定義

全部 Collection 定義放在 imports/schema 目錄, 每一個 Collection 務一定義 Schema 來約束字段

Schema 定義

Schema 定義使用 SimpleSchema, 數據插入數據庫前必須經過 schema 校驗, 調用校驗語句爲 表名.schema.validate(要插入的數據);

過濾 Collection 字段

默認狀況下, 數據查詢語句會返回全部字段, 好比 Memete.users.find({}) 會將用戶的密碼和 token 一併返回, 這樣是不安全不正確的, find / findOne 的第二個參數是查詢選項, fields 字段能夠控制返回字段, 例如:

Meteor.users.find(
    { },
    {
        fields: {
            username: 1,
            profile: 1,
        },
    },
);

該查詢會返回 _id, username, profile 字段, 其中 _id 是默認返回的

本身定義populate方法(取出關聯數據)

在作邀請新的好友入羣的時候,添加新的好友,利用reywood:publish-composite並不會自動更新數據,因此之後直接本身在客戶端定義方法
這樣作的好處是解決了取關聯數據不會自動更新的bug,可是有點麻煩的是每次須要關聯數據的時候必須在客戶端調用一次方法,正在考慮有沒有更好的解決方法

import { Meteor } from 'meteor/meteor';

const PopulateUtil = {
    group(group) {
        if (group) {
            group.members = Meteor.users.find({ _id: { $in: group.members } }).fetch();
            group.admin = Meteor.users.findOne({ _id: group.admin });
        }
    },
    groups(groups) {
        groups.forEach(group => PopulateUtil.group(group));
    },
};

export default PopulateUtil;

由於此次項目須要本身設計數據庫,還有本身定義後端方法,以前沒有任何經驗,作到如今也總結出一點心得:

• 數據庫設計必定要根據具體的業務邏輯(開始設計以前必定要和產品溝通清楚產品邏輯)
• 能在後端取到的數據,在接口定義的時候不要讓前端去傳

最後感受後端的邏輯真的很複雜,須要各類判斷,各類狀況都得想到

推薦看一下這本代碼大全(第二版),等看完這本書再好好的完善一下這篇文章

參考

class如何命名更規範
代碼大全(第二版)
Commit Message 編寫指南

About

github
blog