current community

your communities

more stack exchange communities

Stack Exchange
tour help
Take the 2-minute tour ×
Code Review Stack Exchange is a question and answer site for peer programmer code reviews. It's 100% free, no registration required.
up vote 0 down vote favorite

In JavaScript, I wrote a class that can be optionally instantiated with the new keyword, but can also be called statically as well. What is the best way to demonstrate this behavior in comment syntax? I was thinking something like this:

// localize constant
var PI = Math.PI;

/**
 * Complex constructor
 * optionally instantiate with `new`
 *
 * @class Complex
 * @constructor
 * @static
 * @param r {Number} real part
 * @param i {Number} imaginary part
 * @param m {Number} optional, magnitude
 * @param t {Number} optional, argument
 * @return {Object} complex number
 */

function Complex(r, i, m, t) {
    if (!(this instanceof Complex)) {
        return new Complex(r, i, m, t);
    }

    if (typeof m === 'number') {
        this.m = Math.abs(m);
    } else {
        this.m = Math.sqrt(r * r + i * i);
    }

    if (typeof t === 'number') {
        this.t = (m >= 0 ? t : t + PI);
    } else {
        this.t = Math.atan2(i, r);
    }

    // limit argument between (-pi,pi]
    this.t = PI - (PI * 3 - (PI - (PI * 3 - this.t) % (PI * 2))) % (PI * 2);
    this.r = r;
    this.i = i;
}
share|improve this question
1  
Can't you use words instead of r, i, m, t –  JaDogg Jul 5 at 8:02
    
@Bhathiya I suppose I could but they're referenced 100s of times in the file so it saves a lot of typing. –  Patrick Roberts Jul 5 at 18:30
    
You can start with names like that and then refactor to proper ones. –  JaDogg Jul 6 at 2:01

1 Answer 1

up vote 2 down vote

Naming

As Bhathiya pointed out, you should be using actual, descriptive variable names rather than just a single character.

A descriptive variable name means everything, as it increases readability and understanding 10-fold, even if it means typing a few more characters each time you write the variable name.

And, if you really, really don't want to type out a full variable name each time, most text editors or IDEs come with auto-complete. This could help you type less.

I think that the best way to express that the class can be instantiated in comment form would be to write something like this:

@instantiate: (new) Complex(r, i, m, t);

Then, in your code, I recommend adding a comment to these lines:

if (!(this instanceof Complex)) {
    return new Complex(r, i, m, t);
}

That says that those lines allow for the object to be instantiated with new.

However, do you really need both options? Is there something in the full program that you are using that blocks you from using new? I can't think of any case where you would be blocked by using new, I think you should always use it because it is then very clear that Complex is a class.

share|improve this answer
    
@PatrickRoberts I apologize. I did not think I could give you a strong answer to your direct question, so I gave a short review on something that I noticed on your code. I did not intend for this to be your best answer; I just wanted to point something out. If you'd like, I could delete this answer. –  SirPython Jul 6 at 16:47
    
@PatrickRoberts I edited my answer. Does this answer your question, now? –  SirPython Jul 6 at 16:53
1  
I also have a static function called Complex.Polar() that requires new to be omitted. Making it optional for Complex() allows other developers using the library to remain consistent by omitting new for both constructors, and saving them the confusion of having to explain why one constructor uses new and the other doesn't. –  Patrick Roberts Jul 6 at 20:34

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.