JavaScript 开发代码规范指南
1. 代码格式
1.1 缩进
- 使用 2 个空格进行缩进
- 不要混用空格和制表符
// ✅ 正确
function calculateTotal(items) {
let total = 0;
items.forEach(item => {
total += item.price * item.quantity;
});
return total;
}
// ❌ 错误
function calculateTotal(items) {
let total = 0; // 使用4空格或制表符
items.forEach(item => {
total += item.price * item.quantity;
});
return total;
}
1.2 分号
- 语句结尾始终使用分号
// ✅ 正确
const name = "John";
const age = 25;
// ❌ 错误
const name = "John"
const age = 25
1.3 行长度
- 每行代码不超过 80 个字符
- 超过时进行合理换行
// ✅ 正确
const result = calculateTotalPrice(
items,
taxRate,
discount
);
// ❌ 错误
const result = calculateTotalPrice(items, taxRate, discount, shippingCost, promotionCode);
2. 命名规范
2.1 变量和函数
- 使用 camelCase 命名法
- 名称应具有描述性
// ✅ 正确
let userName = "Alice";
const MAX_RETRY_COUNT = 3;
function getUserInfo() {
// ...
}
// ❌ 错误
let un = "Alice"; // 缩写不明确
const maxretrycount = 3;
function getuserinfo() { }
2.2 类和构造函数
- 使用 PascalCase 命名法
// ✅ 正确
class UserAccount {
constructor(name, email) {
this.name = name;
this.email = email;
}
}
function DatabaseConnection() {
// ...
}
// ❌ 错误
class userAccount { }
function database_connection() { }
2.3 常量
- 使用 UPPER_SNAKE_CASE
- 仅在值真正不变时使用
// ✅ 正确
const API_BASE_URL = "https://api.example.com";
const DEFAULT_TIMEOUT = 5000;
// ❌ 错误
const apiBaseUrl = "https://api.example.com";
const default_timeout = 5000;
3. 变量声明
3.1 使用 const 和 let
- 优先使用 const
- 需要重新赋值时使用 let
- 避免使用 var
// ✅ 正确
const user = { name: "John" };
let count = 0;
user.age = 25; // 对象属性可以修改
count = 1;
// ❌ 错误
var userName = "John";
count = 1; // 未声明变量
3.2 变量分组
- 相关变量应分组声明
// ✅ 正确
// DOM 元素
const form = document.getElementById("user-form");
const input = document.getElementById("user-input");
const button = document.getElementById("submit-btn");
// 配置常量
const API_URL = "https://api.example.com";
const TIMEOUT = 5000;
const MAX_RETRIES = 3;
// ❌ 错误
const form = document.getElementById("user-form");
const API_URL = "https://api.example.com";
const input = document.getElementById("user-input");
const TIMEOUT = 5000;
4. 函数规范
4.1 函数声明
- 使用函数声明而非函数表达式（需要提升时）
- 箭头函数用于匿名函数和回调
// ✅ 正确
function calculateTotal(price, quantity) {
return price * quantity;
}
// 回调函数使用箭头函数
const numbers = [1, 2, 3];
const doubled = numbers.map(num => num * 2);
// ❌ 错误
const calculateTotal = function(price, quantity) {
return price * quantity;
}
4.2 参数处理
- 参数不超过 3 个，过多时使用对象参数
- 使用默认参数替代逻辑判断
// ✅ 正确
function createUser({ name, email, age = 18, role = "user" }) {
return {
name,
email,
age,
role
};
}
// ❌ 错误
function createUser(name, email, age, role, isActive, createdAt) {
age = age || 18;
role = role || "user";
// ...
}
5. 对象和数组
5.1 对象字面量
- 使用简写属性
- 方法使用简写语法
// ✅ 正确
const name = "John";
const age = 25;
const user = {
name,
age,
getInfo() {
return `${this.name} - ${this.age}`;
}
};
// ❌ 错误
const user = {
name: name,
age: age,
getInfo: function() {
return this.name + " - " + this.age;
}
};
5.2 数组方法
- 优先使用数组方法而非 for 循环
// ✅ 正确
const numbers = [1, 2, 3, 4, 5];
const evenNumbers = numbers.filter(num => num % 2 === 0);
const doubled = numbers.map(num => num * 2);
// ❌ 错误
const evenNumbers = [];
for (let i = 0; i < numbers.length; i++) {
if (numbers[i] % 2 === 0) {
evenNumbers.push(numbers[i]);
}
}
6. 异步编程
6.1 Promise 和 async/await
- 优先使用 async/await
- 正确处理错误
// ✅ 正确
async function fetchUserData(userId) {
try {
const response = await fetch(`/api/users/${userId}`);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error("Failed to fetch user data:", error);
throw error;
}
}
// ❌ 错误
function fetchUserData(userId) {
return fetch(`/api/users/${userId}`)
.then(response => response.json())
.catch(error => console.error(error));
}
7. 错误处理
7.1 明确的错误处理
- 使用 try-catch 处理可能出错的代码
- 抛出有意义的错误信息
// ✅ 正确
function parseJSON(jsonString) {
try {
return JSON.parse(jsonString);
} catch (error) {
throw new Error(`Invalid JSON: ${error.message}`);
}
}
class ValidationError extends Error {
constructor(field, message) {
super(`Validation failed for ${field}: ${message}`);
this.field = field;
}
}
// ❌ 错误
function parseJSON(jsonString) {
return JSON.parse(jsonString); // 未处理可能的错误
}
8. 注释规范
8.1 文档注释
- 使用 JSDoc 格式注释函数和类
- 注释应说明目的而非实现
// ✅ 正确
/**
* 计算订单总价
* @param {Array} items - 订单项数组
* @param {number} taxRate - 税率 (0-1)
* @param {number} discount - 折扣金额
* @returns {number} 订单总价
*/
function calculateOrderTotal(items, taxRate = 0.1, discount = 0) {
const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
return (subtotal - discount) * (1 + taxRate);
}
// ❌ 错误
// 计算总价
function calc(items, tax, disc) {
let total = 0;
// 遍历所有商品
for (let i = 0; i < items.length; i++) {
total += items[i].price * items[i].quantity; // 价格乘以数量
}
return (total - disc) * (1 + tax); // 减去折扣加上税
}
9. 模块化
9.1 ES6 模块
- 使用 import/export 而非 require/module.exports
- 明确导出和导入
// ✅ 正确 - math.js
export const PI = 3.14159;
export function add(a, b) {
return a + b;
}
export default class Calculator {
// ...
}
// ✅ 正确 - app.js
import Calculator, { PI, add } from './math.js';
// ❌ 错误
const PI = 3.14159;
module.exports = { PI };
10. 代码质量
10.1 单一职责
- 函数和类应专注于单一功能
- 避免过长的函数
// ✅ 正确
function validateEmail(email) {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
}
function sendWelcomeEmail(user) {
if (!validateEmail(user.email)) {
throw new Error("Invalid email address");
}
const emailContent = generateWelcomeEmail(user);
return emailService.send(user.email, emailContent);
}
// ❌ 错误
function processUser(user) {
// 验证、发送邮件、更新数据库等全部混在一起
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(user.email)) {
return false;
}
// 发送邮件逻辑...
// 更新数据库逻辑...
// 其他各种逻辑...
}
11. 工具和自动化
11.1 使用 ESLint
// .eslintrc.json
{
"extends": ["eslint:recommended"],
"rules": {
"indent": ["error", 2],
"quotes": ["error", "single"],
"semi": ["error", "always"],
"no-unused-vars": "error",
"no-console": "warn"
},
"env": {
"browser": true,
"es6": true
}
}
11.2 使用 Prettier
// .prettierrc
{
"semi": true,
"trailingComma": "es5",
"singleQuote": true,
"printWidth": 80,
"tabWidth": 2
}
记住：代码是写给人看的，只是顺便让计算机执行。
浙公网安备 33010602011771号