PATTERNS

explain code

Always write your code for two main audiences:

1. a computer that will compile and execute your code;
2. a person who will read your code and try to make sense of it.

The second audience may be yourself in the future, when you return to a script that you wrote after some time has passed. It may be an instructor in this course who wants to help you troubleshoot something in your script that is not working. Or it may be someone you have never met who is looking to adapt and recycle parts of your script for a slightly different purpose. Whoever the reader may be, you should always aim to help people read your code by placing explanations directly in your workflow.

The patterns below describe different ways to explain your code and make it more readable for a human audience.

script header

Write a header at the top of your script.

At a minimum, the header should identify who wrote the script, when they wrote it, and why they wrote it. This is also where many authors will define the license for the script.

I usually include a couple lines of repeating symbols to visually block the header and separate it from the rest of the script.

/*    
// ><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><

    AUTHOR:   
    DATE:     
    TITLE:  

// ><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><
*/

task description

Write a line comment before each major task in your workflow.

Describe what you are doing or why you are doing it. Use full sentences and correct punctuation (start each comment with a capital letter and end each comment with a period).

I usually include a line of repeating symbols above and below the task description to help visually separate the code into discrete chunks.

// -------------------------------------------------------------
//  To illustrate a task description.
// -------------------------------------------------------------

---

This work is licensed under CC BY-NC-SA 4.0