The correct way for document object parameters to a function in javascript

Question

Say I have this function:

function func(someObject){ ... }

What's the correct way to tell the consumer what the contents of "someObject" are? Is this something I should even worry about?

I was thinking that I should at least describe the input object in the module description. Is that okay?

EDIT: I just want to know the correct pattern to avoid confusion. I know javascript is dynamically typed.

EDIT2: I want people on my team to be able to know the arguments within an object without having to go to through the code.

EDIT3: Is the correct way to add that information above the function in a comment or to add it to a package specific readme?

EDIT3: It seems like the thing I was looking for was JSDOC:

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Possible duplicate of [Set type for function parameters?](https://stackoverflow.com/questions/8407622/set-type-for-function-parameters) — Ayaz Ali Shah, Mar 04 '18 at 09:00
Not really. I know its dynamically typed. I just want to know the correct pattern to avoid confusion. — Narwhal, Mar 04 '18 at 09:01
Pleasae define "_consumer_". A developer reading your code base or the function receiving the argument? Something else? — Teemu, Mar 04 '18 at 09:22
I want people on my team to be able to know the arguments within an object without having to go to through the code. — Narwhal, Mar 04 '18 at 15:58
@NicholasKyriakides Would the correct way to do that be a comment block above a function or a package specific readme? — Narwhal, Mar 04 '18 at 16:03
@str http://usejsdoc.org/ I googled js doc and found this. This is exactly what I was looking for. Thanks! Thanks for putting up with my inability to convey my need coherently. — Narwhal, Mar 04 '18 at 16:05
@Maz The best solution is to autogenerate documentation from comments, jsDoc is a really nice package that does this for you AFAIK. FWIW I've voted to reopen your question after your latest edit. — nicholaswmin, Mar 04 '18 at 16:08
How would yall suggest I fix the title so that it helps other people? — Narwhal, Mar 04 '18 at 16:10
[Here's how](https://stackoverflow.com/a/6460748/673991) to JSDoc the members of a passed object. For example `* @param {object} someObject` then `* @param {string} someObject.member` — Bob Stein, Mar 04 '18 at 18:55

Ahmad · Answer 1 · 2018-03-05T15:45:05.020

3

If you want to protect your code from being abused, you could use some sort of type checking.. instanceof is an example. See my snippet for details

class Dog {
    constructor(name) {
       this.name = name;
    }
    bark() {
       console.log('woof!');
    }
}

class Cat {
    constructor(name) {
       this.name = name;
    }
    meow() {
      console.log('meow!!!!!');
    }
}


function only_dogs(animal) {
   if(animal instanceof Dog) {
      console.log(animal.name + ' says: ');
      animal.bark();
   } else {
      console.log(animal.name + ' is not a dog..');
   }
}

var animal1 = new Dog("Pluto");
var animal2 = new Cat("Felix");


only_dogs(animal1);
only_dogs(animal2);

This way, the function bark() will be guaranteed to be called only on valid objects that the function expects. Since animal2 is a Cat, it doesn't know how to bark() but you should not worry about that if you check its type before calling its methods.

edited Mar 05 '18 at 15:45

answered Mar 04 '18 at 09:13

Ahmad

12,336
6
48
88

Good insight: if you find yourself passing objects to functions, you may want instead to make it a **member function** of a class. – Bob Stein Mar 04 '18 at 18:58
Since you're the only one that made an answer, rather than a comment, do you wanna reference JSDocs in it as well? Then I'll just give you the green check. – Narwhal Mar 05 '18 at 15:42
@Maz I added a link to instanceof documentation on mozilla https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof – Ahmad Mar 05 '18 at 15:46

The correct way for document object parameters to a function in javascript

1 Answers1