像讲故事一样在写代码

依赖于注释会让代码需要更长的时间来阅读和消化。你应该考虑一下代码如何继续存在。毕竟这是一个未来好多年，别人会来阅读的故事。

const sendResult = (dbConfig, query) => {
  // 连接数据库
  const db = getConnection(dbConfig);
  /* 计算所有学生的考试成绩的函数 */
  const users = db.sendQuery(query);
  const results = users.map(user => ({ id: user.id, result: result }));

  /* 生成带有结果的邮箱 */
  const html = generateHTML(results);
  sendEmail(html);
}

创建额外的函数来解释代码。需要添加注释的应该是创建新变量或新函数的操作调用。较小的函数更容易测试，并会使代码干净整洁。

const getStudentResults = (dbConfig, query) => {
  const dbConnection = getConnection(dbConfig);
  const users = dbConnection.sendQuery(dbConfig, query);
  return users.map(user => ({ id: user.id, result: result }));
}

const emailResults = () => {
  const html = generateHTML(results);
  sendEmail(html);
}

const sendResult = (dbConfig, query) => {
  const resuls = getStudentResults(dbConfig, query);
  emailResultse(resuls);
}

使用 JSDoc 之类的东西记录高级函数是注释的理想用例。

/**
 * 从数据库中获取学生成绩
 * @param {object} dbConfig - 数据库连接配置
 * @param {string} query - 数据库查询语句
 */
const getStudentResults = (dbConfig, query) => { }

免责声明：有注释的时间和地点。我并不反对注释本身，只是反对过度使用注释，明明整洁的代码是更好的选择。

当别人阅读你的代码时，你应该尽可能的让他人可以轻松搞定。我可不想因为需要不停的计算而毁了一个好的故事。

const user = getStudentResults(4309394);
// 我需要在大脑中计算，以弄清楚 if 语句发生了什么
if (user.result < 40 || user.attendance < 50) {
  sendEmail(user, false);
} else {
  sendPassMail(user, true)
}

分配新的变量来存储语句的结果可以使代码阅读者了解故事。代码的读者试图找到他们关心的部分。帮助他们了解故事，以便他们可以修复错误或添加该功能。这个故事将有共同作者。

const user = getStduentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendEmail(user, false);
} else {
  sendEmail(user, true)
}

myFunction(null, undefined, 1) 在任何故事中都不是一个最好的开头。不要让你的读者钻研函数，所以看看参数是怎么做的。

const user = getStudentResults(4309394);

if (user.result > 40 && user.attendance > 5) {
// false 在这儿是什么意思，我可猜一猜，但它应该是个明确的
  sendEmail(user, false);
} else {
  sendEmail(user, true)
}

在这儿，传递对象可能是一个很好的解决方案。

const sendEmail = ({ user, passedCourse }) => { }

const user = getStudentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendEmail({ user, passedCourse: true });
} else {
  sendEmail({ user, passedCourse: false });
}

通过创建一些新功能，您可以使您的故事更具表现力。

const sendEmail = ({ user, passedCourse }) => { }

const sendPassEmail = (user) => {
  sendEmail({ user, passedCourse: true });
}

const sendFailEmail = (user) => {
  sendEmail({ user, passedCourse: false });
}

const user = getStudentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendPassedEmail(user);
} else {
  sendFailEmail(user)
}

避免魔数。与上面那些模棱两可的论点类似，魔数具有我们故事中不希望出现的那种阴谋

const getStudents = (courseId, fieldOfStudy) => {}

const students = getStudents('323424', 4);

const getStudents = (courseId, studentType) => {}
const courseId = '323424';
const fieldsOfStudy = {
    ENGINEERING: 4,
    BUSINESS: 5
};

const students = getStudents(courseId, fieldsOfStudy.ENGINEERING);

与神奇数字一样，使用字符串作为标识符可能会导致混淆。在字符串中使用 id 会导致歧义。重构这些字符串将更加困难。

getResults({ entity: 'undergrad', courseId: 'SCIENCE_101'});

// 在代码的其他地方
getResults({ entity: 'undergrad', courseId: 'SCIENCE_101'});
getResults({ entity: 'undergrad', courseId: 'SCIENCE_100'});

const entity = {
  UNDERGRAD: 'underGrad',
  POSTGRAD: 'postGrad',
}

getResultsFromDB({ entity: entity.UNDERGRAD, courseId: 'SCIENCE_101'})

更好的是，使用 typescript 来加强类型安全。

不要让你的读者感到迷惑。我们的代码应该干净，整洁。当时函数命名不需要受到长度的限制。

const results = getResults();

const examResults = getStudentExamResults();

你还有什么技巧吗？
让我在评论中看到你的代码片段吧。