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