首次發(fā)表在個人博客
總結(jié)一下個人在開發(fā)及review同事代碼的過程中遇到的因為一些項目規(guī)范帶來的問題及認(rèn)為比較好的解決方法;
由于個人經(jīng)驗和認(rèn)知水平有限,下面僅代表我的個人觀念,歡迎各位大佬多給我提建議;
以本人最近寫的一個項目(技術(shù)棧為Meteor + React + MongoDB)為例
readme的使用
因為一個項目往往需要很多人一起協(xié)助開發(fā),還有可能會不斷有新手接手項目,所以readme里面一定要僅可能多的信息
- 項目啟動命令
- 代碼規(guī)范
- Commit Message 編寫規(guī)范
- 命名: class命名,變量命名,函數(shù)命名,組件命名等
- 組件
- 目錄結(jié)構(gòu)
- 常遇到的問題及解決方案
也可以加一些項目中遇到的設(shè)計到的文檔鏈接
代碼規(guī)范
Commit Message 編寫規(guī)范
編寫Commit Message需要遵循一定的范式，內(nèi)容應(yīng)該清晰明了，指明本次提交的目的，便于日后追蹤問題。
feat: 新功能
fix: 修補(bǔ)bug
docs: 文檔
style: 格式(不影響代碼運行的變動)
refactor: 重構(gòu)
test: 添加測試
chore: 構(gòu)建過程或輔助工具的變動
命名
命名的語義化真的特別特別重要,哪怕不知道要命名的這個詞的英文是什么,也要去查一下;千萬不要以a,b,c等沒有任何語義的詞去命名;之前我也總是注意不到這一點,但是最近在看同事的代碼還有重構(gòu)自己之前寫的部分代碼,命名壓根看不明白這個變量的意思,總之,看這樣的代碼怎一個痛苦了得
常見class命名關(guān)鍵詞：
布局類：header, footer, container, main, content, aside, page, section
包裹類：wrap, inner
區(qū)塊類：region, block, box
結(jié)構(gòu)類：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
狀態(tài)類：active, current, checked, hover, fail, success, warn, error, on, off
導(dǎo)航類：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...
變量命名: 名字要能準(zhǔn)確的描述出該變量所代表的事物
比如表示user的id就叫userId,而不要只叫user
函數(shù)命名建議：可使用常見動詞約定
動詞 含義
get 獲取某個值
set 設(shè)置某個值
is 判斷是否為某個值
has 判斷是否有某個值
以下規(guī)則是此項目中使用的,主要看團(tuán)隊代碼習(xí)慣:
- 組件名和組件所在文件名使用大駝峰式
- css類名使用小寫單詞并用橫線(-)分割
- dom節(jié)點以$開頭
組件
- 每個組件占一個文件
- 組件不包含狀態(tài)則應(yīng)寫為 stateless 組件
- 非 stateless 組件使用 pure-render-decorator 優(yōu)化
目錄結(jié)構(gòu)
├── client
│ ├── main.html 客戶端頁面模板
│ └── main.js 客戶端入口
├── imports
│ ├── client
│ │ ├── App.jsx 頂層組件
│ │ ├── components 公共組件
│ │ ├── routers 前端路由
│ │ ├── styles 樣式
│ │ └── views 視圖
│ │ ├── header 公共頭
│ │ ├── login 登錄注冊
│ ├── schema 模型
│ └── util 工具函數(shù)
├── packages 自定義 meteor 包
├── public 客戶端資源
└── server
├── main.js 服務(wù)端入口
└── user 用戶接口
issues的使用
項目中總會遇到很多奇奇怪怪的問題,當(dāng)時印象深刻,過了一段時間,就忘了具體的問題及解決辦法,雖然每次可以通過查commit為fix的記錄,但是這樣查找起來很麻煩,我們項目是用gitlab來托管,可以合理的理由issues,每次遇到很棘手的問題的時候,可以提一個issues,等后期把這個問題解決了再把這個issues給關(guān)閉,并寫上問題原因及解決辦法分析
下面補(bǔ)充的是項目中針對Meteor后端開發(fā)的一些規(guī)范
數(shù)據(jù)庫
Collection 定義
所有 Collection 定義放在 imports/schema 目錄, 每個 Collection 務(wù)必定義 Schema 來約束字段
Schema 定義
Schema 定義使用 SimpleSchema, 數(shù)據(jù)插入數(shù)據(jù)庫前必須通過 schema 校驗, 調(diào)用校驗語句為 表名.schema.validate(要插入的數(shù)據(jù));
過濾 Collection 字段
默認(rèn)情況下, 數(shù)據(jù)查詢語句會返回所有字段, 比如 Memete.users.find({}) 會將用戶的密碼和 token 一并返回, 這樣是不安全不正確的, find / findOne 的第二個參數(shù)是查詢選項, fields 字段可以控制返回字段, 例如:
Meteor.users.find(
{ },
{
fields: {
username: 1,
profile: 1,
},
},
);
該查詢會返回 _id, username, profile 字段, 其中 _id 是默認(rèn)返回的
自己定義populate方法(取出關(guān)聯(lián)數(shù)據(jù))
在做邀請新的好友入群的時候,添加新的好友,利用reywood:publish-composite并不會自動更新數(shù)據(jù),所以以后直接自己在客戶端定義方法
這樣做的好處是解決了取關(guān)聯(lián)數(shù)據(jù)不會自動更新的bug,但是有點麻煩的是每次需要關(guān)聯(lián)數(shù)據(jù)的時候必須在客戶端調(diào)用一次方法,正在考慮有沒有更好的解決方法
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;
因為這次項目需要自己設(shè)計數(shù)據(jù)庫,還有自己定義后端方法,之前沒有任何經(jīng)驗,做到現(xiàn)在也總結(jié)出一點心得:
- 數(shù)據(jù)庫設(shè)計一定要根據(jù)具體的業(yè)務(wù)邏輯(開始設(shè)計之前一定要和產(chǎn)品溝通清楚產(chǎn)品邏輯)
- 能在后端取到的數(shù)據(jù),在接口定義的時候不要讓前端去傳
最后感覺后端的邏輯真的很復(fù)雜,需要各種判斷,各種情況都得想到
推薦看一下這本代碼大全(第二版),等看完這本書再好好的完善一下這篇文章
參考
class如何命名更規(guī)范
代碼大全(第二版)
Commit Message 編寫指南
