src backend contributors coding_style

Backend Style

File Structure

Copyright Notice

All files should begin with the standard copyright notice:

/*
 * Copyright (C) 2025-present Puter Technologies Inc.
 *
 * This file is part of Puter.
 *
 * Puter is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

Imports

const express = require('express');
const passport = require('passport');

const { get_user } = require("../../helpers");
const BaseService = require("../../services/BaseService");
const config = require("../../config");

const path = require('path');
const fs = require('fs');

Import order is generally:

1. Third party dependencies. Having these occur first makes it easy to quickly determine what this source file is likely to be responsible for.
2. Files within the module.
3. Standard library, "builtins"

Code Formatting

Indentation and Spacing

const fn = async () => {
    const a = 5; // Spaces between operators

    // Note: "=" in for loop initializer does not require space around
    // Note: operators in condition part have space around
    for ( let i=0; i < 10; i++ ) {
        console.log('hello');
    }
    
    // Control structures have space inside parenthesis
    for ( const thing of stuff ) {
        // NOOP
    }
    
    // Function calls do not have space inside parenthesis
    await something(1, 2);
}

• Use 4 spaces for indentation.
• Use spaces around operators (=, +, etc.); not required in for loop initializer.
• Use a space after keywords like if, for, while, etc.

  return [1,2,3]; // Sure
  return[1,2,4];  // Definitely not

• Use spaces between parenthesis in control structures unless parenthesis are empty.

  if ( a === b ) {
    return null;
  }

• No trailing whitespace at the end of lines
• Use a space after commas in arrays and objects
• Empty blocks should have the comment // NOOP within braces

Line Length

• Try to keep lines under 100 characters for better readability
  • Try to keep them under 80, but this is not always practical
• For long function calls or objects, break them into multiple lines

Trailing Commas

// This is great
{
    "apple",
    "banana",
    "cactus", // <-- Good!
}

// This is also fine
[
    1, 2, 3,
    4, 5, 6,
    7, 8, 9,
]

[
    something(),
    another_thing(),
    the_last_thing() // <-- Nope, please add trailing comma!
]

We use trailing commas where applicable because it's easier to re-order lines, especially when using vim motions.

Braces and Blocks

• Single statement blocks must either be on the same line as the corresponding control structure, or surrounding by braces:

  if ( a === b ) return null; // Sure
  if ( a === b )
      return null; // Please no 🤮
  if ( a === b ) {
      return null; // Nice
  }

• Opening braces go on the same line as the statement
• Put a space before the opening brace

Naming Conventions

Variables

• Variables are generally in camelCase
• Variables might have a prefix_beforeThem

const svc_systemData = this.services.get('system-data');
const svc_su = this.services.get('su');
effective_policy = await svc_su.sudo(async () => {
    return await svc_systemData.interpret(effective_policy.data);
});

In the example above we see the svc_ prefix is used to indicate a reference to a backend service. The name of the service is system-data which is not a valid identifier, so we use svc_systemData for our variable name.

Classes

• Use PascalCase for class names
• Use snake_case for class methods
• Instance variables are often snake_case because it's easier to read. camelCase is acceptable too.
• Instance variables only used internally should have a trailing_underscore_ even if in camelCase_. We avoid using #privateProperties because it unnecessarily inhibits debugging and patching.

File Names

• Use PascalCase for class files (e.g., UserService.js)
• Use kebab-case for non-class files (e.g., auth-helper.js)

Documentation

JSDoc Comments

• Backend services (classes extending BaseService) should have JSDoc comments
• Public methods of backend services should have JSDoc comments
• Include parameter descriptions, return values, and examples where appropriate

/**
 * @class UserService
 * @description Service for managing user operations
 */

/**
 * Get a user by their ID
 * @param {string} id - The user ID
 * @returns {Promise<Object>} The user object
 * @throws {Error} If user not found
 */
async function getUserById(id) {
    // ...
}

Inline Comments

• Use inline comments to explain complex logic
• Prefix comments with tags like track: to indicate specific purposes

// track: slice a prefix
const uid = uid_part.slice('uid#'.length);