Naming, Casing, and Commenting Conventions
Last updated
Last updated
Naming, casing, and commenting are critical to software engineering because they help us communicate what our code does, preventing miscommunication and bugs. The following are Rocket Academy's naming, casing, and commenting conventions.
In general, variable names should be as specific as needed to prevent miscommunication. For example, for a card game with 2 representations of a card, one the card's HTML element and one a JS Object containing the card's name, suit, and rank, we might name the former cardElement and the latter cardMetadata. Avoid naming either variable card to prevent miscommunication.
Avoid using shorthand in variable names that might be common in , because such terminology may not be universal and can cause confusion and bugs. Strive for precision and concision, prioritising the former where necessary. For example, in Singapore it may be common to use the letter "n" as an abbreviation for "and" and the letter "w" as an abbreviation for "with". Avoid these in variable names because they may not be universal.
Function names should start with a verb. This is to distinguish functions from data that might take a similar name. For example, the function getRandomNum may return a random number that gets stored in a variable randomNum.
Boolean variable names should start with a question word. This is to clearly communicate that this variable stores a boolean. For example, isGameOver and hasPlayerWon would be preferred boolean variable names than gameOver and playerWon because the former more explicitly store booleans.
By convention, we typically name callback functions that handle events with the prefix handle and suffix event type. For example, we would name the callback function for an onClick event handleClick.
Sometimes we have variables that are constant in our program and used in multiple places, for example number of starting points in a game. To communicate clearly what these constants are and prevent bugs due to string or number misspelling, we often store these variables in "constant" variables, typically near the top of our file or in a separate constants.js file.
SCREAMING_SNAKE_CASE. MY_ENV_VAR.
Lowercase. E.g. <div>
Lowercase kebab-case. E.g. <div my-attr="lowercase">hello</div>
UpperCamelCase. E.g. MyReactComponent
IDs and classes in kebab-case. Prefix related classes with common prefix for organisation, e.g. .card-image and .card-text.
Git branches are typically named with kebab-case, e.g. my-new-feature.
URL entities that consist of multiple words are separated by hyphens. For example, www.mysite.com/my-url-entity.
SQL table names should be plural and in snake_case, and column names should be singular and in snake_case. SQL is case-insensitive, and SQL commands such as CREATE and WHERE are often capitalised, thus lowercase is preferred for column names. Underscores are preferred over hyphens to separate words because hyphens are special characters in some SQL implementations.
Comments should only exist to clarify code
Start comments with a capitalised word like we would an English sentence
Inline comments go directly above the line or lines they are commenting on
By default, JavaScript uses for variable names. Treat acronyms like regular words and use for greater readability, e.g. cardHtmlElement instead of cardHTMLElement.
Constants are typically cased with by convention, e.g. NUM_STARTING_POINTS.
There is no definitive file naming case convention for JS. Rocket Academy prefers because it's easier to navigate between words than , where word processors do not consider underscores to be word separators. Some teams use CamelCase for React component file names; this is subjective so long as we are consistent.
For function-level comments in JS, consider using for clearer identification of functions and what they do. JSDoc is a standard format for JS comments, as well as a tool that auto-generates HTML pages that document code files.
The @ symbol in JSDocs signifies a "tag"- some structure of the code to document. In Rocket Academy JavaScript documentation we will be almost exclusively using only the param and return tags in JSDoc formatted comments. See the full list of tags .