Skip to content

Naming Guidelines for gaslamp

1. Overview

This document defines naming conventions used throughout the gaslamp project.

It aims to:

  • Promote consistency and clarity across the codebase
  • Make code easier to read, review, and maintain
  • Ensure compatibility with both Google Apps Script and Node.js environments

The guide is intended for:

  • Core gaslamp developers
  • Contributors working on modules such as DataFrame, Expression, etc.
  • Anyone writing unit tests, utilities, or documentation in the project

2. General Principles

This section outlines the foundational principles for naming across the gaslamp codebase.

camelCase vs PascalCase

  • Use camelCase for variables, function names, and object keys.
  • Use PascalCase for class names and constructor functions.
JavaScript
const rowIndex = 2;
function getColumnNames() { ... }

class DataFrame { ... }
const df = new DataFrame(data);

Abbreviations and Clarity

  • Use abbreviations like df, expr, and cfg when they are project-standard and widely understood.
  • Do not use ambiguous or overly short names like a, b, tmp unless used in a tight local scope.

Context-Aware Naming

  • Use variable names based on their role:
  • row vs record (row of a DataFrame vs generic JSON-like object)
  • ctx for execution context or test harness
  • options for optional parameters with default behavior

GAS/Node.js Compatibility

  • Do not shadow global GAS objects (e.g., SpreadsheetApp, Logger) in local variable names.
  • Prefer neutral, lowercase names for compatibility:
  • OK: sheet, spreadsheet
  • Avoid: SpreadsheetApp, DriveApp (unless explicitly required)

3. Variable Naming Conventions

3.1 Primitive and Basic Values

Use clear and descriptive names for primitive values, especially when they play a specific role in computation.

  • value: a general-purpose single value
  • key: often used in key-value mappings
  • index: used for positions in arrays or iteration
  • count: used when tracking totals or occurrences

3.2 Data Structures

Use specific names that reflect the structure and intent of the data.

  • obj: a generic object with flexible fields
  • map: a Map instance, typically key-value pairs
  • array: a flat list or simple data sequence
  • record: a row of structured data (e.g. from CSV or JSON)
  • row: a DataFrame row (Map or object form)
  • col: a Series or column-level data
  • df: a DataFrame instance

3.3 Functional Arguments

Use function names that clearly begin with a verb to indicate the operation performed.

  • fn: generic function argument
  • predicate: function that returns true/false (used in filter conditions)
  • transform: function that maps input to output
  • validator: function that checks validity of a value

3.4 Contextual Names

Use these to refer to surrounding context or configuration.

  • ctx: context object (test, execution, rendering)
  • env: environment (e.g., GAS, Node.js, production)
  • config: static configuration object
  • options: optional parameters passed to a function
  • state: dynamic runtime state

4. Class and Instance Naming

4.1 Built-in and Custom Classes

Class names should use PascalCase and describe the structure or behavior clearly.

  • DataFrame: tabular data structure with column-oriented access
  • Expression: lazy evaluation wrapper for DataFrame operations
  • TypeChecker, TestSuite, Logger: utility classes should also follow this format
JavaScript
class DataFrame { ... }
const df = new DataFrame(data);

class Expression { ... }
const expr = Expression.col('age').gt(30);

4.2 Instance Variables

When storing instances of core gaslamp classes, use short, consistent variable names that reflect their type and purpose.

  • df: instance of BareFrame
  • expr: an Expression instance
  • row: a row as Map<string, Cell> (returned by getRow, passed to filter predicates)
JavaScript
const df = BareFrame.fromColumns({ name: ["Alice"], age: [30] });
const row = df.getRow(0);  // Map<string, Cell>

5. Function Naming Patterns

5.1 Verbs and Actions

Function names should begin with a verb to clearly indicate the operation performed.

  • getX: retrieve a value or object (e.g. getRow, getColumn)
  • setX: assign or update a value (e.g. setName, setValue)
  • addX: insert a new item or structure (e.g. addColumn)
  • removeX: delete or exclude something (e.g. removeDuplicates)
  • filterX: return a subset of data based on a predicate
  • mapX: transform each element of a collection
  • reduceX: aggregate elements into a single value

5.2 Conversion

Use toX / fromX prefixes to indicate data transformations.

  • toArrays(), toObjects(): convert internal structures to plain JavaScript types
  • fromArrays(arrays), fromSheet(sheet): create new instances from external formats

5.3 Validation

Use function names that perform type or structure checking with standard keywords:

  • isX: returns true if value matches type/condition.
  • ensureX: throws error if validation fails.
  • assertX: performs a runtime type check and asserts the result to the type system. Throws an error if validation fails.
JavaScript
isString(value);         // true/false
ensureArray(data, 'fn'); // throws if not an array

6. Test Naming Guidelines

6.1 Test Declaration

Use clear and concise names for test suites and individual tests.

  • describe("ClassName"): groups tests related to a specific class
  • describe("methodName"): groups tests for a specific method
  • it("should do something") or test("should do something"): defines expected behavior
JavaScript
describe("DataFrame", () => {
  test("should filter rows by expression", () => {
    const expr = Expression.col("age").gt(30);
    const filtered = df.filter(expr);
    expect(filtered.length).toBe(2);
  });
});

6.2 Result Variables

Use names like result, actual, expected for clarity in assertions.

JavaScript
const actual = df.length;
const expected = 4;
expect(actual).toBe(expected);

6.3 Setup and Context

  • Use module-level let variables for shared state in tests
  • Use beforeAll / beforeEach hooks to prepare and clean up
JavaScript
describe("DataFrame", () => {
  let df;

  beforeAll(() => {
    df = BareFrame.fromArrays([["name", "age"], ["Alice", 30]]);
  });

  test("should filter rows", () => {
    const result = df.filter(Expression.col("age").gt(25));
    expect(result.length).toBe(1);
  });
});

7. GAS-Specific Naming Notes

7.1 Sheet and Spreadsheet Objects

Use lowercase, neutral names to refer to GAS objects without clashing with built-in global names.

  • spreadsheet: refers to an instance of Spreadsheet
  • book: sometimes used as an alias for spreadsheet in multi-book logic
  • sheet: refers to an instance of Sheet (i.e. SpreadsheetApp.getActiveSheet())
  • range: refers to a Range object

Do not reuse Google Apps Script global class names as variable names:

  • Avoid: Logger, SpreadsheetApp, Range, Sheet
JavaScript
const book = SpreadsheetApp.getActiveSpreadsheet();
const sheet = spreadsheet.getActiveSheet();
const range = sheet.getRange("A1:B10");

7.2 Reserved Names and Conflicts

Do not shadow built-in objects. Avoid using names like:

  • Object, Date, Array, Function, Map, Set

If needed, use prefixes like raw, src, gas:

  • OK: gasRange, rawMap, srcSheet

8. Appendix: Common Abbreviations

The following abbreviations are used consistently in the gaslamp codebase.

Abbreviation Meaning Typical Usage
df DataFrame const df = new DataFrame(...)
expr Expression const expr = Expression.col(...)
col Column const col = df.getColumn(...)
cfg Config loadConfig(cfg)
ctx Context describe("suite", (ctx) => ...)
env Environment if (env === 'GAS')
val Value val.toString()
obj Object validateObject(obj)
rowMap Row as Map df.getRow(0, { format: 'map' })
rowObj Row as Object df.getRow(0, { format: 'object' })

9. Commit Message Guidelines

We follow the Conventional Commits format with short descriptive titles and concise bullet-point summaries.

The type categories and scope are not enforced strictly, but developers are encouraged to include them, as these messages are used to generate the changelog.

Text Only
<type>(<scope>): <summary>

- bullet point 1
- bullet point 2
- bullet point 3

Example:

Text Only
feat(book): add BookManager class with named CacheBox support

- Replace global cache logic with BookManager class
- Introduce BookManagerOptions with `name` (default: "book")
- Improve modularity and cache traceability across modules

Common types:

  • feat: New feature
  • fix: Bug fix
  • refactor: Code refactor (no behavior change)
  • docs: Documentation-only changes
  • test: Test-related changes
  • chore: Maintenance work (e.g. config, deps, ...)