WriteMe Coding Standards Document

1. Code Style
2. Naming Conventions
3. Comments
4. Error Handling
5. Linting & Formatting
6. File Structure
7. Branching
8. Commits & Pull Requests

Introduction

This document outlines the coding conventions and styles that our team follows to ensure our code is uniform, clear, flexible, reliable, and efficient. Adhering to these standards will help maintain consistency across our codebase, making it easier to read, maintain, and collaborate on projects.

General Conventions

Code Style

1. Indentation: We use tabs for indentation with a length of two spaces.
2. Line Length: Limit lines to 80 characters. This improves readability and makes it easier to have multiple files open side by side.
3. Semicolons: Always use semicolons to terminate statements.
4. Quotes: Use single quotes for strings, except to avoid escaping.
5. Trailing Commas: Use trailing commas where valid in multi-line constructs (e.g., arrays, objects).

Naming Conventions

1. Variables: Use camelCase for variable names.
2. Constants: Use UPPER_CASE for constant values
3. Functions: Use camelCase for function names.
4. Classes: Use PascalCase for class names.
5. Files: Use kebab-case for filenames.

Comments

1. Single Line Comments: Use ' // ' for single-line comments.
2. Multi-line Comments: Use ' /* ... */ ' for multi-line comments.
3. Documentation Comments: Use ' [//]: #comment ' for comments made in documentation.

//Comments Example
/**
 * Function to add two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 */
function add(a, b) {
  return a + b;
}

Error Handling

For error handling, try-catch-finally statements are used to ensure that errors are properly caught and handled, and any necessary cleanup is performed.

try {
  // Code that might throw an error
} catch (error) {
  // Handle the error
} finally {
  // Code that will run regardless of an error occurring
}

Linting & Formatting

We use Prettier for code formatting to enforce a consistent style across our codebase. The configuration for Prettier is as follows:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": true
}

Prettier is integrated into each of our IDEs and configured to save on format, making it easier to maintain consistency automatically.

File Structure

The repository follows a structured and logical file organization to make navigation intuitive and to segregate different types of files effectively. Below is the standard file structure for our projects:

.
├── apps
│   ├── writeme #Nextjs app
│   │   ├── app
│   │   │   └── api # additional api routes
│   │   ├── public
│   │   └── specs
│   ├── writeme-docs # documentation website
│   │   ├── docs
│   │   ├── guides
│   │   ├── src
│   │   │   ├── components
│   │   │   ├── css
│   │   │   └── pages
│   │   └── static
│   │       └── img
│   └── writeme-e2e # end-to-end tests for writeme app
│       └── src
├── wmc  # components library
│   └── src
└── wmc-utils # utilities for components library
    └── src

Branching Strategy

Our branching strategy is designed to ensure a smooth workflow and maintain the stability of the main codebase.

Branching

Main Branch: The main branch contains the stable, production-ready code. Development Branch: The dev branch is the primary branch for ongoing development. Feature Branches: Developers should create feature branches from dev for new features, bug fixes, or any significant work. The naming convention for feature branches is feat/feature-name.

Process

1. Branch Off: Always branch off dev for new work.
2. Commits: Commit changes regularly to your feature branch. Small, frequent commits make it easier to track changes and roll back if needed.
3. Pull Requests: Once the feature is complete, create a pull request (PR) from your feature branch to dev. At least one reviewer is required to review and approve the PR before it can be merged.
4. Merge: After approval, merge the feature branch into dev. Resolve any conflicts that arise during merging.

Commits & Pull Requests

• Commit Messages: Write clear, concise commit messages that describe the changes made. Use the following format: feat(type): detailed message
  • Type: Indicates the type of change (e.g. fix, docs, style, refactor, test, chore, component, page). Example:

    feat(fix): fixed an error in the SignUp component that allowed duplicate email registration.
• Pull Requests:
  1. Description: Provide a detailed description of the changes made in the pull request.
  2. Review: Ensure that at least one team member reviews and approves the PR.
  3. Testing: Make sure all tests pass before merging the PR.