Best practices for documentation

Keep lines under 80 characters

To make your code easy to read, keep lines under 80 characters. This makes it easier to skim and debug.

Bad:

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.0/css/all.css" integrity="sha384-REHJTs1r2ErKBuJB0fCK99gCYsVjwxHrSU0N7I1zl9vZbggVJXRMsv/sLlOAGb4M" crossorigin="anonymous"p>

Better:

<link 
  rel="stylesheet" 
  href="https://use.fontawesome.com/releases/v5.12.0/css/all.css" 
  integrity="sha384-REHJTs1r2ErKBuJB0fCK99gCYsVjwxHrSU0N7I1zl9vZbggVJXRMsv/sLlOAGb4M" 
  crossorigin="anonymous">

Use comments

Add comments to your code to explain why you made certain decisions. This reduces the chance that future colleagues break your work.

Level 0: No comments

section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden'); 

section.dataset.order = sectionData[ 'sectionOrder'];
section.dataset.name = sectionData[ 'sectionID']; 

if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

 

Level 1: Translate code into English or French

// Add the section and hidden classes
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden'); 

// Add dataset attributes
section.dataset.order = sectionData[ 'sectionOrder'];
section.dataset.name = sectionData['sectionID']; 

// Update header attributes and parent
if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Level 2: Explain what you did

// Style the section
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden'); 

// Add section metadata
section.dataset.order = sectionData[ 'sectionOrder'];
section.dataset.name = sectionData['sectionID']; 

// Add a header to the section
if (sectionData['sectionTitle']) {
  header.innerText = sectionData[ 'sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Level 3: Explain why you did what you did

// dpd-section adds basic styling
// dpd-hidden hides sections that aren't first in order
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden'); 

// Add useful attributes to select the section later
section.dataset.order = sectionData['sectionOrder'];
section.dataset.name = sectionData['sectionID'];

// If optional header is specified, add a label
if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Add function/method docstrings

For every function or class method you create, add a docstring that summarizes the function's purpose, input parameters, and output values.

updateVisibleOptions(id, options) {
  /* 
  Updates visibility of specified options using dropdown query. 
  
  Parameters
    ---------------
  id (type: string)
  - Identifies the dropdown query to be used when filtering. 
  options (type: array)
  - Array of DOM Elements to update the visibility of. 
  */
  
  if (this.#queries[id] === undefined) this.#queries[id] = "";
  
  let visible = filterOptions(options, this.#queries[id]);
  
  // Update element display
  for (let o of options) {
    if (visible.includes(o)) o.classList.remove('dpd-invisible');
    else if (!o.classList.contains('dpd-option-select-all')) 
      o.classList.add('dpd-invisible');
  }
}

Split your code into chunks

Breaking your code into smaller pieces makes it easier to read and maintain.

• You could split a main.js file into a data.js file for data processing, a listeners.js file for user input, and a graph.js file for generating graphs.
• This CodePen example shows how to create small sub functions.
• You could use sub conditions

set sections(list) {
  // sub condition one
  const validArr = Array.isArray(list);
  
  // sub condition two
  let hasObjs = true;
  for (let el of list) {
    hasObjs = hasObjs && (typeof el === 'object');
  }   
  
  // main condition
  if (validArr && hasObjs) this.#sections = list;
  else
    console.error('list must be an array with 1+ object(s) as element(s)');
  }
}

Additionally, organizing files into subsections with clear headings can help readers navigate your code easily:

Date modified:

2023-04-12