翻译进度
5
分块数量
1
参与人数

分享高可读性 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) => { }

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

MasterShu 翻译于 2周前

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)
}
MasterShu 翻译于 2周前

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)
}
MasterShu 翻译于 2周前

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 来加强类型安全。

MasterShu 翻译于 44分钟前

6. Favor verbosity over brevity

Don’t confuse your readers. Our code should be dry, concise and clean but our function names don’t need to be restricted by length.

Bad:

const results = getResults();

Good:

const examResults = getStudentExamResults();

What tips do you have?
I would love to see some code snippets in the comments.

本文章首发在 LearnKu.com 网站上。

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

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

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

参与译者:1
讨论数量: 0
(= ̄ω ̄=)··· 暂无内容!

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