Skip to content

JavaScript

Jump to bottom
Carstairs edited this page Jun 12, 2019 · 3 revisions

Closure

Yeah, it's tough to grok, and Javascript's weird, but it's important.

Encapuslation

Keep your variables to yourself!

JavaScript Comments

There are two schools of thought on Javascript comments:

  1. comments say why & code says what and how
  2. comments stand alone and you can skip the code

We use the second one -- it’s faster to scan through comments written in English than read through code details.

As automated documentation programs continue to proliferate, the second philosophy brings with it the opportunity to have the comments become the documentation, which informs the type and content of the comments.

Comment Types, Places & Format

Overview

  • At the beginning of the function, or block of related functions.
  • Contains the goal, context, business reasons, and dependencies.
  • Formatted in a standardized multi-line block, with a title or short description and then a longer detailed section and information on dependencies. Each section begins with an asterisk and a space.

Functional

  • Inside functions to explain why a function was written the way it was, what variables are used for, what subsections do.
  • Larger comments should use the /**/ syntax, but don’t need titles or line breaks except as needed for readability.
  • Single line comment should use the // syntax and address the whys and why-fors of bits of code.
  • Use spaces after and before the end asterisks or slashes.

Examples

Overview

/*
* Order Table Interactivity – slide down table rows (Title or short description)
*
* Displays detailed information about an order’s multiple shipments (aka gens, generations) 
* in a slide down section. The data is pulled via ajax when the order is clicked on and displayed
* inside a new row with specific styles to make it appear secondary to the original row.
*
* Dependencies & Related: function dateCleanup (global.js) – content passed for formatting
*/

Functional

/* Create the HTML structure which gets displayed inside the slide down row and add the content to the structure */

// row indexOf links row that is clicked-on to slide down insertion location

Clone this wiki locally