分享高可读性 JavaScript 代码的技巧:如讲故事一样在写代码

F2E 前端

你写的不仅仅是代码,更是写一个故事。

这有一些关于如何给未来的自己以及其他开发者写代码的提示。

1. 使用函数和变量来表达你的意图,而不是注释

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

坏:

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) => { }

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

2. 使用变量来解释控制语句

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

坏:

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)
}

3. 避免含糊不清的参数

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)
}

4. 魔法在某些故事中使好用的,但不包括我们

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

坏:

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);

5. 使用枚举。避免使用字符串作为标识符。

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

Bad:

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

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

Good:

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

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

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

6. 喜欢冗余大于简单

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

坏:

const results = getResults();

好:

const examResults = getStudentExamResults();

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

本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://dev.to/collinstommy/your-code-sh...

译文地址:https://learnku.com/f2e/t/41430

本文为协同翻译文章,如您发现瑕疵请点击「改进」按钮提交优化建议
讨论数量: 0
(= ̄ω ̄=)··· 暂无内容!

请勿发布不友善或者负能量的内容。与人为善,比聪明更重要!