[!] Dev Handbook

[yusufaine]

For internal use only

Table of Content

Sadly the links aren't working

• 1. Coding Convention
  • 1.1. TypeScript
    • 1.1.1. Formatting
    • 1.1.2. Names
    • 1.1.3. Types
    • 1.1.4. Functions
    • 1.1.5. Variables
    • 1.1.6. Imports
    • 1.1.7. Paradigm
    • 1.1.8. Comments
• 2. Git & GitHub
  • 2.1. Branches and Workflow
  • 2.2. Commits
  • 2.3. Pull Requests
  • 2.4. Reviews
  • 2.5. Configurations
    • 2.5.1. Logs
    • 2.5.2 Tree
• 3. IDE
  • 3.1. Visual Studio Code (VSC)
    • 3.1.1. Extensions

---

1. Coding Convention

1.1. TypeScript

For all new codebases, both eslint and prettier must be installed and strictly adhered to. Most formatting and linting issues discussed here can be solved by simply formatting your files automatically using your IDE.

1.1.1. Formatting

• Always use double quotes for strings "hi!"

• Always terminate all statements with a semicolon

• Always use 2 spaces per indentation/tab

• Always prefer braces

  // Always this
  if (ok) {
    console.log("hello");
  }
  
  // Over this
  if (ok) console.log("hello");

1.1.2. Names

• Types: use PascalCase

• Classes: use PascalCase

• Enums: use PascalCase for names, but SCREAMING_SNAKE_CASE for values

  enum EnumExample {
    FIRST_VALUE = "1",
    SECOND_VALUE = "2",
  }

• Variables and functions: use camelCase

• Object property names: use camelCase

• Prefer whole words when possible

1.1.3. Types

• Strongly prefer types over interfaces (only use interfaces when describing an interface of an OOP class)

• Prefer combinations of unions and Pick/Omit over copy pasting a previously defined type

  type TypeA = {
    a0: string;
    a1: string;
  };
  type TypeB = {
    b0: string;
    b1: string;
  };
  
  // Prefer this
  type NewType = TypeA & TypeB;
  
  // Over this
  type NewType = {
    a0: string;
    a1: string;
    b0: string;
    b1: string;
  };

• Prefer type annotations (: Foo) over type assertions (as Foo) whenever possible to allow easier detection of bugs when types change

1.1.4. Functions

• Always use arrow functions over anonymous function expressions

  // Prefer this
  [].map(() => { ... });
  
  // Over this
  [].map(function () { ... });

• Prefer pure functions unless performance is necessary

1.1.5. Variables

• Always prefer const over let if the variable is not mutable (an array can be mutable but if the reference to said array is not mutable, const should be used)
• Never use var — NEVER
• Avoid global variables unless strictly necessary

1.1.6. Imports

• Import statements should be separated into two different sections, library imports and local imports, with exactly one new line between

  // library imports including our own library (if any) always at the top
  import { ... } from "axios";
  import { ... } from "lodash";
  import { ... } from "ourLib";
  
  // local imports always after library imports
  import { ... } from "../logic";
  import { ... } from "src/constants";

• Unused imports should be removed or at the very least commented out (if taking something out temporarily)

1.1.7. Paradigm

• Prefer OOP for backend and internal services especially if they are non-trivial pieces of software (ie. more than 1k loc)
• Prefer ESM-style import/export for the codebase
• Prefer functional programming (like use of map / reduce / filter) over a general for loop (for better readability and maintainability)

1.1.8. Comments

• If it isn’t immediately obvious why certain code is written some way, provide suitable comments
• Use JSDoc style comments for external functions, classes, interfaces, enums, and constants where necessary

2. Git & GitHub

2.1. Branches and Workflow

• All branches should follow this convention:

  <name>/<feat|fix>-<short description>
  
  dev01/feat-user-db-crud
  dev02/fix-user-db-deletion
  

2.2. Commits

• All commit messages should follow the semantic commits convention and in present tense
  • ie. for a feature: feat: add subscribe buttons
• Keep each commit to a reasonable logical change

2.3. Pull Requests

• Titles should give a brief description of the main task (you may, but not necessarily, follow the same conventions as commit messages)
  • ie. for a bug fix: fix input sometimes not working
• Provide suitable descriptions of all changes if need be
• Make a PR as soon as you make your first commit and label the PR as status: doing
  • This allows any reviewer to immediately understand where you are at and help if need be
• Push to the PR as soon as you make new commits so as to ensure that the remote branch is as updated as possible to prevent losing your work
• PRs should have at least one approval by the codeowner before being merged to main
• Always choose the “squash and merge” option when merging a PR (❗: TO CONFIRM WITH PROFS)
• For documentation purposes, DON'T delete any branches after merging

2.4. Reviews

Requesting for reviews:

1. Ensure all changed files have been properly formatted (Refer to 1.1.1. Formatting)
2. Ensure all changed files are strictly necessary and for your PR only and revert the unnecessary changes
   • ie. if working on an isolated feature, try not to have formatting changes to files that you didn’t even touch in the first place → a new refactor PR for such files should be created)
3. Merge the main branch into the PR first (ie. git pull origin main)
4. Label the PR as status: done
5. Request a review from the codeowner or other team members with experience
6. (Optional) Ping the reviewer if need be

2.5. Configurations

2.5.1. Logs

Sorry Blake 😭

To get a better git log experience, we can alias git lg to the following (note that we use lg and not log in case you still want the inferior experience):

git config --global alias.lg "log --pretty=format:'%C(magenta)%h%Creset -%C(red)%d%Creset %s %C(green)(%cr) [%an]' --abbrev-commit -30"

2.5.2 Tree

Similarly you can view the tree and history

git config --global alias.tree "log --graph --abbrev-commit --decorate --format=format:'%C(magenta)%h%C(reset) - %C(green)%aD%C(reset) %C(dim green)(%ar)%C(reset)%C(brightred)%d%C(reset)%n'' %C(white)%s%C(reset) %C(dim white)- %an%C(reset)' --all"

3. IDE

3.1. Visual Studio Code (VSC)

• The preferred IDE
• Download from https://code.visualstudio.com/
• Comes with TypeScript support out of the box

3.1.1. Extensions

Add more if necessary

• ESLint
• Prettier
• Better Comments: highlight comments in your code
• GitLens: git, but super-powered
• Todo Tree: allows you to see all areas of code with TODO