rspec/rules/S930/javascript/rule.adoc

== Why is this an issue?

When you call a function in JavaScript and provide more arguments than the function expects, the extra arguments are simply ignored by the function.


[source,javascript,diff-id=1,diff-type=noncompliant]
----
function sum(a, b) {
  return a + b;
}

sum(1, 2, 3); // Noncompliant: The last argument is unexpected and will be ignored
----

Passing extra arguments in JavaScript is not inherently "bad," but it can lead to some potential issues or confusion if not handled correctly:

* The function signature is an essential part of its interface. Passing extra arguments can obscure the function's intended use and make it less clear what the function actually requires.
* This can lead to unexpected behavior, as the function might not work as intended or produce incorrect results.
* Code that passes extra arguments can become harder to understand and maintain, especially when revisiting it at a later time.
* Other developers might find it challenging to comprehend the function's purpose if extra arguments are scattered throughout the codebase.
* If you refactor the function later or rely on an external library that changes the expected number of arguments, your code with extra arguments could break unexpectedly.

While it's possible to pass extra arguments, it's essential to note that accessing those extra arguments directly inside the function is not straightforward. One common approach to handling extra arguments is to use the ``++arguments++`` object, which is an array-like object available within all function scopes.

[source,javascript,diff-id=1,diff-type=compliant]
----
function sum() {
  let total = 0;
  for (let i = 0; i < arguments.length; i++) {
    total += arguments[i];
  }
  return total;
}

sum(1, 2, 3); // Compliant
----

However, it's generally recommended to use the rest parameter syntax (``++...args++``) or utilize other techniques like the spread operator to deal with variable numbers of arguments in a more readable and maintainable way.

[source,javascript,diff-id=1,diff-type=compliant]
----
function sum(...args) {
  return args.reduce((a,b) => a + b, 0);
}

sum(1, 2, 3); // Compliant
----

=== Exceptions

No issue is reported when ``++arguments++`` is used in the body of the function being called.

[source,javascript]
----
function doSomething(a, b) {
  compute(arguments);
}

doSomething(1, 2, 3); // Compliant
----

== Resources
=== Documentation

* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments[The ``++arguments++`` object]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters[Rest parameters]
* MDN web docs - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax[Spread syntax (``++...++``)]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

include::../message.adoc[]

=== Highlighting

* Primary: list of arguments
* Additional: list of parameters (in function declaration) 
** message: Formal parameters


'''
== Comments And Links
(visible only on this page)

=== on 29 Apr 2015, 08:02:51 Ann Campbell wrote:
See JSC_WRONG_ARGUMENT_COUNT at \https://developers.google.com/closure/compiler/docs/error-ref

=== on 29 Apr 2015, 08:54:10 Linda Martin wrote:
\[~ann.campbell.2] I would say "[...] doing so *could* lead to unexpected results.", because it could be expected that not all arguments will be given because some are optionals and the body function will check it.


Also what do you think about adding an exception when ``++arguments++`` is used in the body of the function ? 

E.g

----
function f(a, b, c, d) {
 for (var i = 0; i < arguments.length; i++) {
    doSomethingWith(arguments[i]);
  }
}
----


=== on 29 Apr 2015, 12:43:03 Ann Campbell wrote:
I've changed the wording from 'will' to 'could', but I'm against your proposed exception: it requires the author of the call to examine the code of the method being called, which is just not something you should have to do. 

=== on 20 May 2015, 07:09:36 Linda Martin wrote:
\[~ann.campbell.2] not necessarily, documentation exists exactly for this kind of cases.

=== on 20 May 2015, 17:40:29 Ann Campbell wrote:
So can we narrow the exception, [~linda.martin] to: function is documented (there's a comment immediately before it) AND arguments is used in the body?

=== on 2 Jun 2015, 14:29:00 Stas Vilchik wrote:
What to do with optional parameters? Just check the several first functions from http://underscorejs.org/[underscore.js].

=== on 2 Jun 2015, 15:27:09 Ann Campbell wrote:
Per discussion with [~elena.vilchik], the too few args case is ignored by this rule. 

=== on 2 Jun 2015, 15:58:04 Linda Martin wrote:
\[~ann.campbell.2] So no explicit mention of the "exception" in the rule description ?

=== on 2 Jun 2015, 16:32:47 Elena Vilchik wrote:
\[~ann.campbell.2] I've updated description. Assigned to you for validation. CC [~linda.martin]

=== on 3 Jun 2015, 14:39:11 Ann Campbell wrote:
IMO [~linda.martin] no explicit mention needed of ignoring too few args since specialized title narrows the scope.

=== on 4 Jun 2015, 07:47:09 Linda Martin wrote:
OK!

=== on 8 Jun 2015, 11:18:27 Elena Vilchik wrote:
We need to activate this subtask by default (\http://jira.sonarsource.com/browse/RULEAPI-243). Implementation already updated.

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]