Code keeps changing, there’s no doubt about that. We always do our best to set some rock solid code foundations when a new project starts, we even have one or two favorite functions that become the cornerstone of our beautiful program. “This function will be my rod when I walk through the valley of the shadow of death.” But requirements change, and now your function should not just be the rod, but the rod and the staff as well.

代码不断变化，这毫无疑问。 当一个新项目开始时，我们总是尽力为某些基础代码奠定坚实的基础，我们甚至拥有一个或两个最喜欢的函数，这些函数成为了我们漂亮程序的基石。 “当我走过死亡阴影的山谷时，这就是我的职责。” 但是需求发生了变化，现在您的功能不仅应该是杆，还应该是杆和人员。

Let’s take a walk.

让我们出去走走。

转1 (Turn 1)

Let’s imagine a MUD written in Node.js. At some point, we will be implementing melee combat in our game. And you write a function you are very much in love with; it’s a function to calculate the damage inflicted by a melee weapon. For the sake of storytelling, we don’t really care much about the contents of the function. We assume you just love it.

让我们想象一下用Node.js编写的MUD 。 在某个时候，我们将在游戏中实施近战。 并且您编写了一个非常喜欢的功能； 它是计算近战武器造成的伤害的函数。 为了讲故事，我们并不十分在意函数的内容。 我们假设您只是喜欢它。

/*** Calculates the damage of a melee attack.** @param {object} weapon - Weapon used in the attack.* @returns {number} Damage inflicted by <code>weapon</code>.*/
function calculateWeaponDamage(weapon) {return weapon.roll();
}

转2 (Turn 2)

After a couple of days, a game mechanics designer asks you to make some changes in the function because the weapon damage calculation should optionally take into account the physical defenses of the player who is being attacked. Turns out this function is being used both to display average damages in the UI, and to actually calculate the damage in-game when used against a real player. So, sometimes there will be a defender, and sometimes not.

几天后，游戏机制设计人员要求您对功能进行一些更改，因为武器损坏计算应选择考虑被攻击玩家的物理防御能力。 事实证明，此功能既可用于在UI中显示平均伤害，也可用于在对付真实玩家时实际计算游戏中的伤害。 因此，有时会有辩护人，有时没有。

Well, fine! I guess we can add a new argument to the function. We can even try to make the function signature backwards compatible by checking whether the new argument is being passed on or not, so that we do not have to go around refactoring all the usages of calculateWeaponDamage.

好吧，很好！ 我想我们可以向该函数添加新的参数。 我们甚至可以尝试通过检查是否传递了新参数来使功能签名向后兼容，这样我们就不必重新解析calculateWeaponDamage所有用法。

/*** Calculates the damage of a melee attack.** @param {object} weapon - Weapon used in the attack.* @param {object} [defender] - Player who receives the attack.* @returns {number} Damage inflicted by <code>weapon</code> on <code>defender</code>.*/
function calculateWeaponDamage(weapon, defender) {let tmpDamage = weapon.roll();if (defender) {tmpDamage -= defender.stat('defense');}return tmpDamage;
}

Settled down for now, aren’t we?

现在定居下来，不是吗？

转3 (Turn 3)

Hey! We are giving players with extreme strength some melee damage bonus. Do you think you can take this into account in your beloved calculateWeaponDamage function? All developers using your function will be sending you an instance of the player wielding the weapon, because we need this extra damage to be reflected both in the UI and the actual in-game calculations.

嘿! 我们给具有极限力量的玩家一些近战伤害加成。 您认为可以在您钟爱的calculateWeaponDamage函数中考虑到这一点吗？ 所有使用您功能的开发人员都会向您发送持武器玩家的实例，因为我们需要这种额外的损害，才能同时在用户界面和实际游戏计算中得到体现。

— Game mechanics designer

-游戏机制设计师

OK, fine. Now we have three arguments: two mandatory, one optional. But it turns out that other developers don’t have time to do a proper refactoring of the usages of calculateWeaponDamage and, out of desperation, agree to call the function even with an optional argument surrounded by two mandatory ones: calculateDamage(weapon, null, attacker);.

好的。 现在我们有了三个参数：两个强制性，一个可选。 但是事实证明，其他开发人员没有时间适当地重构calculateWeaponDamage的用法，出于绝望，即使使用带有两个必选参数的可选参数也同意调用该函数： calculateDamage(weapon, null, attacker); 。

/*** Calculates the damage of a melee attack.** @param {object} weapon - Weapon used in the attack.* @param {object} [defender] - Player who receives the attack.* @param {object} attacker - Player who inflicts the attack.* @returns {number} Damage inflicted by <code>weapon</code> of <code>attacker</code> on <code>defender</code>.*/
function calculateWeaponDamage(weapon, defender, attacker) {let tmpDamage = weapon.roll() + attacker.stat('extreme');if (defender) {tmpDamage -= defender.stat('defense');}return tmpDamage;
}

At this point you start to feel a bit itchy.

此时，您开始感到有点发痒。

转4 (Turn 4)

You feel they are misusing calculateWeaponDamage. You are tired of changing the signature of the function and decide to try a new approach: let’s use destructured function parameters. That way, the function receives a single options object argument holding as many mandatory or parameters as they want; if, in the future, new parameters should be added, then the refactoring of its usages will not be as painful as before, and as the owner of the function I don’t have to break my head too much about its signature — it’s just adding another property to the single object argument.

您觉得他们在滥用calculateWeaponDamage 。 您已经对更改函数的签名感到厌倦，并决定尝试一种新方法： 让我们使用分解后的函数参数 。 这样，函数将接收单个options对象参数，该参数包含所需的任意数量的必需或参数。 如果将来要添加新参数，则其用法的重构将不会像以前那样痛苦，并且作为函数的所有者，我不必为它的签名而费心—只是将另一个属性添加到单个对象参数。

/*** Calculates the damage of a melee attack.** @param {object} options - Options of this function.* @param {object} options.attacker - Player who inflicts the attack.* @param {object} options.weapon - Weapon used in the attack.* @param {object} [options.defender] - Player who receives the attack.* @returns {number} Damage inflicted by <code>weapon</code> of <code>attacker</code> on <code>defender</code>.*/
function calculateWeaponDamage({ attacker, weapon, defender }) {let tmpDamage = weapon.roll() + attacker.stat('extreme');if (defender) {tmpDamage -= defender.stat('defense');}return tmpDamage;
}

转5 (Turn 5)

Change of plans, bud!

计划变更，芽！

We need a bunch of extra options in calculateWeaponDamage: weapons might have imbued elemental damage, so we need a flag to determine whether we should take those into account, we also need a flag to actually inflict the damage on defender instead of just calculating it, and we also […]

我们在calculateWeaponDamage需要大量额外的选择：武器可能受到了元素伤害，因此我们需要一个标志来确定是否应将这些因素考虑在内，我们还需要一个标志来对defender造成实际伤害，而不仅仅是计算它，而且我们[…]

— Game mechanics designer

-游戏机制设计师

Anyway. For some reason or another, they’ve thrown a pile of flags at our function and now its signature just became something like this:

无论如何。 由于某种原因，他们在我们的函数上抛出了一堆标志，现在它的签名变得像这样：

/*** Calculates the damage of a melee attack.** @param {object} options - Options of this function.* @param {object} options.attacker - Player who inflicts the attack.* @param {object} options.weapon - Weapon used in the attack.* @param {object} [options.defender] - Player who receives the attack.* @param {boolean} [options.inflictInDefender=false] - Whether to actually inflict the damage on <code>defender</code>.* @param {boolean} [options.ignoreMagicalResistance=false] - If <code>true</code> magical resistances will be ignored in the calculations.* @param {boolean} [options.ignorePhysicalDefence=false] - If <code>true</code> physical defenses will be ignored in the calculations.* @param {boolean} [options.criticalHitsAllowed=true - Whether to allow critical hit values in the calculations.* @returns {number} Damage inflicted by <code>weapon</code> of <code>attacker</code> on <code>defender</code>.*/
function calculateWeaponDamage({ attacker, weapon, defender, inflictInDefender = true, ignoreMagicalResistance = true,ignorePhysicalDefence = true, criticalHitsAllowed = true}) {// We don't really care what happens inside
}

Would you be happy with this function signature?

您对此函数签名满意吗？

回顾性 (Retrospective)

I’ve found myself guilty of overusing destructured function parameters. Sometimes they felt really convenient, other times those function signatures stuck out like a sore thumb.

我发现自己过度使用解构函数参数是有罪的。 有时，他们感到非常方便，而其他时候，这些功能签名却像大拇指一样伸出来。

The series of unfortunate events that led to the latest calculateWeaponDamage version are probably exaggerated, but hopefully you might have recognized some personal experiences or work patterns in them. With the knowledge we have at this point, this is the function signature I would have proposed:

导致最新的calculateWeaponDamage版本的一系列不幸事件可能被夸大了，但是希望您可能已经意识到其中的一些个人经验或工作模式。 有了我们到此为止的知识，这就是我会建议的功能签名：

• attacker, weapon and defender are the main actors in this function. Semantically, they “weight” more than all the other parameters in the signature. They have the right to be their own arguments in the function.

  attacker ， weapon和defender是此功能的主要参与者。 语义上，它们比签名中的所有其他参数“权重”更多。 他们有权在函数中成为自己的参数。

• We know now that the function will receive an actual set of options. Let’s have those as a separate, namesake object argument. Traditionally, the “options” argument is the last one, but in our scenario we have an optional argument in between: defender.

  现在我们知道该函数将收到一组实际的选项。 让我们将它们作为一个单独的同名对象参数。 传统上， “选项”参数是最后一个参数 ，但是在我们的场景中，我们之间有一个可选参数： defender 。

If we would attempt to do some sort of function overloading by allowing our function to be called in both these ways…

如果我们试图通过允许通过这两种方式调用我们的函数来进行某种函数重载……

• calculateWeaponDamage(attacker, weapon, { ... });

  calculateWeaponDamage(attacker, weapon, { ... });

• calculateWeaponDamage(attacker, weapon, defender, { ... });

  calculateWeaponDamage(attacker, weapon, defender, { ... });

…you’ll end up having errors when using the first example (without defender) because there would be an attempt to destructure an undefined 4th argument:

…使用第一个示例(不使用defender )时，您最终会出错，因为会尝试破坏未定义的第四个参数：

> calculateWeaponDamage(fingonfil, sword, { criticalHitsAllowed: false });Uncaught TypeError: Cannot read property 'inflictInDefender' of undefined

Maybe our function is just not that suitable to have destructured parameters. Still, we could solve the aforementioned error with a more exotic signature:

也许我们的功能不适合具有分解的参数。 不过，我们可以通过更奇特的签名解决上述错误：

/*** Calculates the damage of a melee attack.** @param {object} weapon - Weapon used in the attack.* @param {object} interactives - Interactive creatures involved in the melee attack.* @param {object} interactives.attacker - Player who inflicts the attack.* @param {object} [interactives.defender] - Player who inflicts the attack.* @param {object} options - Options of this function.* @param {boolean} [options.inflictInDefender=false] - Whether to actually inflict the damage on <code>defender</code>.* @param {boolean} [options.ignoreMagicalResistance=false] - If <code>true</code> magical resistances will be ignored in the calculations.* @param {boolean} [options.ignorePhysicalDefence=false] - If <code>true</code> physical defenses will be ignored in the calculations.* @param {boolean} [options.criticalHitsAllowed=true - Whether to allow critical hit values in the calculations.* @returns {number} Damage inflicted by <code>weapon</code> of <code>attacker</code> on <code>defender</code>.*/
function calculateWeaponDamage(weapon, { attacker, defender },{ inflictInDefender = true, ignoreMagicalResistance = true,ignorePhysicalDefence = true, criticalHitsAllowed = true }) {// Do your magic here
}

This way we “won’t” run into TypeError exceptions when there is no defender passed to the function (narrator: we still will.)

这样，当没有防御者传递给函数时，我们“不会”遇到TypeError异常( 旁白：我们仍然会 。)

Because our function is about calculating the damage inflicted by a weapon, weapon deserves to be the first argument. attacker and defender, as the interactive parties involved in the combat, have the same “semantic weight”. We could group them together as the second destructured argument.

因为我们的功能是关于计算武器造成的伤害，所以weapon应该是第一个论点。 作为参与战斗的互动方， attacker和defender具有相同的“语义权重”。 我们可以将它们组合在一起，作为第二个变形的论点。

Unfortunately, if we go for the simplest possible usage of this new function…

不幸的是，如果我们尽可能简单地使用此新功能……

> calculateWeaponDamage(sword, { attacker: fingonfil });

…we are still getting a TypeError exception.

…我们仍然收到TypeError异常。

> calculateWeaponDamage(sword, { attacker: fingonfil })Uncaught TypeError: Cannot read property 'inflictInDefender' of undefined    at calculateWeaponDamage (repl:2:7)

Since the argument options is truly optional, we can default its value to {}, like this:

由于参数options实际上是可选的，因此我们可以将其默认值设置为{} ，如下所示：

/*** Calculates the damage of a melee attack.** @param {object} weapon - Weapon used in the attack.* @param {object} interactives - Interactive creatures involved in the melee attack.* @param {object} interactives.attacker - Player who inflicts the attack.* @param {object} [interactives.defender] - Player who inflicts the attack.* @param {object} [options] - Options of this function.* @param {boolean} [options.inflictInDefender=false] - Whether to actually inflict the damage on <code>defender</code>.* @param {boolean} [options.ignoreMagicalResistance=false] - If <code>true</code> magical resistances will be ignored in the calculations.* @param {boolean} [options.ignorePhysicalDefence=false] - If <code>true</code> physical defenses will be ignored in the calculations.* @param {boolean} [options.criticalHitsAllowed=true - Whether to allow critical hit values in the calculations.* @returns {number} Damage inflicted by <code>weapon</code> of <code>attacker</code> on <code>defender</code>.*/
function calculateWeaponDamage(weapon, { attacker, defender},{ inflictInDefender = true, ignoreMagicalResistance = true,ignorePhysicalDefence = true, criticalHitsAllowed = true } = {}) {// Do your magic here
}

And this my dear reader would be our last version of the function before we give up and move to TypeScript.

我亲爱的读者将是我们放弃并转移到TypeScript之前该函数的最新版本。

我们注意到了什么？ (What have we noticed?)

• Sometimes we will spend an outrageous amount of time trying to get the right name of a function, or an argument. Or pondering on the position of an argument goes. That’s fine.有时，我们会花费大量时间来尝试获得函数或参数的正确名称。 或思考论点的位置。 没关系。
• It helps when the arguments of a function have a semantic meaning and can be weighed. Some of them deserve to be in the spotlight, others can stay more in the backstage area.当函数的参数具有语义含义并可以权衡时，它会有所帮助。 他们中的一些人应该受到关注，其他人可以留在后台。
• Destructured function parameters can help with maintainability but also come with some challenges, like we saw. It’s good to ask oneself: do I really need them here? Is it helping me or making things more complicated?像我们看到的那样，解构的函数参数可以帮助实现可维护性，但同时也会带来一些挑战。 问自己一个很好：我真的在这里需要他们吗？ 是帮助我还是使事情变得更复杂？
• There is a certain convention on what arguments should be in the last position, like callbacks and option objects. If some of those things are present in your function, other developers might expect them to be in that certain position.关于哪些参数应该放在最后位置有一定的约定，例如回调和选项对象。 如果您的函数中存在其中某些内容，则其他开发人员可能希望它们处于该特定位置。

We are documenting our functions with JSDoc, which will also help us see which arguments are optional and which ones have default values. For a more detailed article on bringing your JSDdoc skillsto the next level, check out one of my previous articles:

我们正在使用JSDoc记录我们的函数，这还将帮助我们查看哪些参数是可选的，哪些参数具有默认值。 有关将您的JSDdoc技能提升到更高水平的更详细的文章，请查看我以前的文章之一：