7

I am probably over thinking, but I am having trouble digesting the Nodejs documentation. I am new to javascript and come from a Java Background.

My question is not about any specific nodejs function just overall understanding. Below I give an example of what I am trying to understand...

When working with a statically typed language like Java it is very clear what types are needed for method calls. A trivial example, if I want to sort an array of int's I can just look at Arrays.sort and see that it takes an int[] (same for other types as well). I can also see that it returns void.

public static void sort(int[] a)

However javascript is a dynamic language thus there are no types for api calls. Take this example in the crypto module

crypto.pbkdf2(password, salt, iterations, keylen, callback)
Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive a 
key of given length from      the given password, salt and iterations. 
The callback gets two arguments (err, derivedKey).

So without going out and finding example code, or looking at the nodejs source how do I know the argument types of the function? I realized that it is possible to derive the types by looking at the name (ie callback is a function type) but is there any other way?

For example the documentation says that the callback gets two arguments err and derivedKey. What is the type of derivedKey, what is the type or err? Am I missing something about the documentation? How do you know if you are passing in the right types?

Note: I am already know what the type of derivedKey and err is so I don't need answers like "derivedKey is ...." My question is about overall understanding of the Nodejs documentation for someone coming from a statically typed language and is not specific to crypto.pdkdf2.

Improve this question
2
  • 1
    You're definitely not over-thinking. I have no idea why they wouldn't provide clear documentation of the acceptable parameter types. I haven't really used Node since I started using Go, and forgot about their documentation. Never much cared for it.. Commented Jul 21, 2013 at 21:43
  • 1
    @CrazyTrain Thanks! It is good to hear that. I really thought I was missing something. Commented Jul 21, 2013 at 22:04

2 Answers 2

Reset to default
2

Well you are pretty much over thinking. You'll have to guess most of them if it's not explained explicitly. like you can guess iterations and keylen are numbers rather than strings. NodeJS docs explain parameters explicitly when they think you can't guess, or you have to know something additional about it. like in crypto.createCredentials(details) they explain that details is a dictionary and which keys you need to use. F.i. in case of err and derivedKey, since there is no explicit info, i would have assumed both are strings. If it turns out they are not, i would console.log them in callback function to see what they are.

Documentation could be a lot more clear if they have written down types of all parameters but don't know if it's worth the effort.

Improve this answer
Sign up to request clarification or add additional context in comments.

7 Comments

For what it's worth, I think it is worth the effort to write very explicit documentation. The narrative format of the current docs almost feels like I'm reading a tutorial. I'd much rather see consistent, well-defined, and exhaustive documentation than short parameter descriptions and a few contrived usage examples.
I guess it boils down to personal preference when it comes to things like this. I am ok with both NodeJS's way of documenting and type of docs you are talking about. In NodeJs docs 'contrived' usage examples are provided in some cases. But i agree, sometimes the docs falls short on not leaving any question marks in your head.
It seems that there should be a better way. I guess it just takes some getting used to coming from a statically typed languages.
@Desu: So your preference is less information? A single line by each method would answer lots of questions very quickly.
@naomik I tend to agree. Good documentation is a great time saver.
|
2

I have some experience with C# and Java, and have been programming JavaScript for about a year, so I might be able to frame this.

objects

One aspect of JavaScript is that you can make objects like this, on the spot:

var options = {
    name: "something",
    age: 9,
    what: function() {
        return 8;
    }
};

Everyone takes advantage of this, so it's a big key to understanding JavaScript libraries.

You can also take the above options object and then go like this:

options.mood = "ok";

In other words, objects are just bundles of properties, and the structure isn't set. You can use language constructs like the for ... in loop to iterate through them. That is to say, the "type" of things like err is basically an associative array.

callbacks

Callbacks are basically everywhere, so the question becomes how to deal with them. A common pattern is function (err, maybeSomething). Most of the time, you only care if err is "something." That is, you'll go like this a lot:

if (err) {
    ...
}

Frankly, I do a lot of console.log(err) to see what I'm getting back during development.

After that it's really up to the documentation. Some of it is better than others. You're not really missing anything. About the only "trick" is that sometimes a doc will explain everything at the top.

You'll find yourself going into the source sometimes to find out what exactly a library is doing, but 97% of the time a few quick guesses and checks will get you moving.

Improve this answer

1 Comment

That makes sense. I was just hoping there was a more elegant solution. :)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.