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