Use the atom-beautify or prettier-atom package to format your code automatically! It won’t do absolutely everything you need, but it will do most of it. In the settings, enable formatting code on save so that it happens automatically.
When programming, it’s really important to keep our code nicely formatted. This is most of all so that we can read it easily ourselves, but also so that other people can read it too. This mostly means:
;)Poorly formatted example:
let circle={x:0,y:250,speed:1,size:100}
function setup()
{
createCanvas(500,500)}
function draw(){
background(0);
circle.x=circle.x+circle.speed
ellipse(circle.x,circle.y,circle.size);
}
function mousePressed() {
circle.size=circle.size + 10
}
The above example makes many mistakes. For instance:
circle is all on one line with no whitespace and has no semicolonsetup() functioncreateCanvas() isn’t indented and has no semicolon} for setup() is on the same line as createCanvas()setup() function and the draw() functionbackground(0) is not indented correctlycircle.x=circle.x+circle.speed has no semicolon and would be better with spacingellipse() instruction is indented too farellipse() and the closing } of draw()draw() and mousePressed() functionscircle.size=circle.size + 10 is indented too far and has inconsistent spacingA correctly formatted version:
let circle = {
x: 0,
y: 250,
speed: 1,
size: 100
};
function setup() {
createCanvas(500,500);
}
function draw() {
background(0);
circle.x = circle.x + circle.speed;
ellipse(circle.x,circle.y,circle.size);
}
function mousePressed() {
circle.size = circle.size + 10;
}
We write comments in our code to explain it to ourselves and to others. If your code is still confusing to you or others with comments in it, you need to think about writing better comments!
Make sure to write a comment before any block of code that does something cohesive. Your comment should explain what the lines of code after it do, not just literally describe the code. When in doubt, write more comment, not fewer.
The syntax for a comment is to write two forward slashes, //, and then the text of your comment.
// Draw the face/head
ellipse(250,250,200,200);
// Draw the eyes
ellipse(200,250,20,20);
ellipse(300,250,20,20);
// Draw the mouth
ellipse(250,300,50,50);
Some people like to comment next to their lines of code, and this is fine too:
ellipse(250,250,200,200); // Draw the face/head
ellipse(200,250,20,20); // Draw the left eye
ellipse(300,250,20,20); // Draw the right eye
ellipse(250,300,50,50); // Draw the mouth
Every function in your program (recognizable because they start with function) should have a comment above it that explains what the function does. It should also explain any parameters it needs and any values it returns if relevant.
// setup()
//
// Draws a simple face on the canvas
function setup() {
createCanvas(500,500);
background(0,0,0);
// Draw the face/head
ellipse(250,250,200,200);
// Draw the eyes
ellipse(200,250,20,20);
ellipse(300,250,20,20);
// Draw the mouth
ellipse(250,300,50,50);
}
At the top of every JavaScript file (.js) you should have a comment that describes the file. This is most important for your main screen (usually script.js), which should have a description of your project at the top. Your description should be fairly detailed and give an overview of anything relevant to the project’s implementation and purpose.
It is common to use a “multi-line comment” for these kinds of descriptions (and sometimes for functions too), which we write by starting with /* and ending with */.
script.js:
/***********************
Face drawing machine
Pippin Barr
Draws a face on the canvas
***********************/
function setup() {
createCanvas(500,500);
background(0,0,0);
// Draw the face/head
ellipse(250,250,200,200);
// Draw the eyes
ellipse(200,250,20,20);
ellipse(300,250,20,20);
// Draw the mouth
ellipse(250,300,50,50);
}
README.mdAny formally submitted project should include a file titled README.md in the main project folder. This document should explain your project and should provide any information someone interested in it might need to understand the implementation and also how to interact with it. It should clearly state the title of the project as well as your authorship.
The README.md is also a good place for attribution if you are using code and/or media from other sources that you need to credit.
Example:
# Aquarium Simulation
## Pippin Barr
This is an aquarium simulation in which fish of different kinds swim around on the canvas. The user can interact with the fish by clicking on them to make them grow (as if feeding them). Over time the fish shrink, so the user will need to keep busy clicking to keep them alive!
The fish images were sourced from the [Creative Commons image "Georgia Aquarium Fish"](https://search.creativecommons.org/photos/96f6f770-eac1-488c-8abb-16bee7bcc874) by Mike Johnston which is licensed with CC BY 2.0. To view a copy of this license, visit https://creativecommons.org/licenses/by/2.0/.
Naming variables involves both technical constraints as well as style rules.
circleX for your circle’s x position, not flimFlam, cX)secretGardenPassword, not secretgardenpassword, not secret_garden_password)$ and _, but avoid them). (starDensity, not *density, not %starDenity%)mouseImageX, not mouseX because it is used by p5; classStatus, but not class because it is a JavaScript reserved word)circleX is not the same as circlex)Whenever you find yourself needed more than one variable that relates to the same “thing” in your code (like a circle you are animating), you should use a JavaScript object instead of individual variables.
// Yes!
let circle = {
x: 0,
y: 0,
size: 100,
speed: 1
};
// No.
let circleX = 0;
let circleY = 0;
let circleSize = 100;
let circleSpeed = 1;
Naming functions follows the same essential rules as variables.
displayFish() to display a fish, not df(), fishRay())displayFish(), now DisplayFish(), not displayfish(), not display_fish())$ and _, but avoid them). (displayFish(), not displayFish!())displayImage(), not image() because it is used by p5; create(), but not new() because new it is a JavaScript reserved word)displayFish() is not the same as displayfish())Always use version control (Git and GitHub) with your programming projects. There is literally never a good reason not to use it.
Because this class uses one repository for multiple projects, we will always put a prefix in front of our commit messages to indicate which project they are for (e.g. “E1” for exercise 1 or “P2” for project 2).
When you start a new project make sure to create an initial commit that marks the start of the project (usually when you have just placed some template code in a folder named for the project).
We want to avoid projects where we commit once at the start and once at the end. The idea is to create a history of our project through our commits and their commit messages.
Therefore, each time you get a unit of work done, commit it with a message. This might be getting an image to display correctly on the canvas, making the mouse control a specific element successfully, or getting a sound effect to work.
Your commit messages should be fairly brief, but they should concisely describe exactly what you did since the previous commit. For example. E2: Got the mouse controls working or P1: Now the snake moves according to a sine wave.
It’s important to push your work to the remote server to keep it extra safe. Don’t forget. You don’t have to push after every commit, but you should certainly push when you’re stopping work for a while.
Whenever you use code or media from somewhere else you must attribute it to give credit, this includes:
The general idea is to make it very clear what about your project was “pre-made” versus what it completely new.
To attribute, make sure to include the place you found the code/media and the original author.
Much code and media online comes with a specific license (e.g. the Creative Commons) which you must respect. Make sure you read the licensing agreement and follow it.
For media, you can attribute
README.md file in your project folderFor code, you can attribute