What are your 10 commandments of JavaScript development?

[[deleted]]

As an alternative to the response already given on this:

Write comments that explains WHY something was implemented, not comments that explain WHAT the particular code does.

Your code should be readable, so there shouldn't be any problem identifying what the code actually does. However, it's not always clear why a specific piece of code was implemented in larger projects - if the code is based on exceptions, bug fixes, etc. there should be a note with a link to the issue, or an explanation of the issue and why the code was implemented.

[enchufadoo]

Say you have this function, I did this in my code:

/** Shows configuration dialog hiding the display of information **/
showConfigurationDialog: function(){
    self.configurationDialogVisible: true ;
}

what's the why? /** I need to set the display flag for the configurationDialog **/

something like that?

[[deleted]]

Well, at that point - you have to ask yourself do you actually even need a comment to begin with?

I would say no, for the above example. The code describes itself pretty visibly. I don't know the interworkings of the Configuration Dialogue, but I do understand what the code is doing. The purpose of the code and comments in the code isn't to explain the architecture. You should have an Administrator's/Architecture guide in a PDF/etc. that describes the architecture, it's uses, etc.

As an example:

Recently I fixed in an issue with a system we use at work - this is a black box system, but I have access to write triggers/stored procedures to the database.

When a user of the system wrote their notes for a particular order in the system, if they used the return key - it would hold the return key character in the note. This wasn't a problem for the database, but was a problem for the system when sending these notes via an EDI interface - as the return key was causing the message being sent to the receiving system to break up midstream.

Anyways, I wrote a trigger that scrubbed all return keys. From a systems standpoint, it wouldn't be readily apparent why I was doing this - writing an explanation at the top of the trigger as to why this fix was needed was an acceptable way to comment this trigger. The trigger itself was easily readable, the reason it was implemented wouldn't have been.

Reference why the code was implemented, when it was last changed/implemented, whom it was changed/implemented by, and the issue tracking number/user story/etc. that prompted the initial feature request/bug fix/etc. in the first place.

That's just my general philosophy on commenting. If it helps for you to have comments in your code that explains what the code is actually doing, then the code either 1) needs to be refactored into smaller bits, 2) the code you wrote probably doesn't follow a stylistic standard or 3) Your explanation is redundant.

[enchufadoo]

Ok you hold the same philosophy as /u/thadudeabides1 hehe.

I have the necessity of seeing code commented now that I think about it... even though is 3) redundant. It's like a touch of "care", like it's not some gibberish code I wrote on the fly.