Code Standards

Guidelines for writing clean, maintainable code.

JavaScript Standards

General Rules

• Use ES6+ features
• Prefer const over let
• Never use var
• Use arrow functions for callbacks
• Use template literals

Naming Conventions

// Variables and functions: camelCase
const userName = "John";
function formatDistance() {}

// Constants: UPPER_SNAKE_CASE
const MAX_FILE_SIZE = 100 * 1024 * 1024;

// Classes: PascalCase
class StateManager {}

// Files: camelCase or kebab-case
formatDistance.js;
mapUtils.js;

Function Style

// Prefer arrow functions for simple functions
const add = (a, b) => a + b;

// Use regular functions for methods and complex logic
function processFileData(data) {
 // Complex logic
}

// Always document functions
/**
 * Formats a distance value.
 *
 * @param {number} meters - Distance in meters
 *
 * @returns {string} Formatted distance
 */
function formatDistance(meters) {
 return `${(meters / 1000).toFixed(2)} km`;
}

Error Handling

// Always handle errors
try {
 const data = await loadFile(path);
 processData(data);
} catch (error) {
 console.error("Failed to load file:", error);
 showErrorToUser("Unable to load file");
}

// Throw meaningful errors
if (!isValid(input)) {
 throw new Error(`Invalid input: expected number, got ${typeof input}`);
}

Module Standards

Single Responsibility

Each module should do one thing:

// ✅ Good: Single responsibility
// formatDistance.js
export function formatDistance(meters) {}
export function convertToMiles(meters) {}

// ❌ Bad: Multiple responsibilities
// mixedHelpers.js
export function formatDistance() {}
export function renderMap() {} // Unrelated

Clear Exports

// Named exports for multiple functions
export function formatDistance(meters) {}
export function formatDuration(seconds) {}

// Default export for main functionality
export default function formatDistance(meters) {}

Documentation

/**
 * Module description.
 *
 * @module formatDistance
 */

/**
 * Formats a distance for display.
 *
 * @example
 *  formatDistance(5000); // "5.00 km"
 *  formatDistance(5000, { unit: "mi" }); // "3.11 mi"
 *
 * @param {number} meters - The distance in meters
 * @param {Object} options - Formatting options
 * @param {string} options.unit - Target unit ('km' or 'mi')
 * @param {number} options.decimals - Decimal places
 *
 * @returns {string} Formatted distance string
 */
export function formatDistance(meters, options = {}) {
 const { unit = "km", decimals = 2 } = options;
 // Implementation
}

CSS Standards

Class Naming

Use BEM or descriptive names:

/* BEM style */
.chart-container {
}
.chart-container__header {
}
.chart-container--fullscreen {
}

/* Descriptive */
.main-map-view {
}
.data-table-wrapper {
}

Organization

/* Group by component */

/* Map styles */
.map-container {
}
.map-controls {
}
.map-fullscreen {
}

/* Chart styles */
.chart-container {
}
.chart-legend {
}

Testing Standards

Test Structure

describe("formatDistance", () => {
 describe("basic formatting", () => {
  it("should format meters to kilometers", () => {
   expect(formatDistance(5000)).toBe("5.00 km");
  });

  it("should handle zero", () => {
   expect(formatDistance(0)).toBe("0.00 km");
  });
 });

 describe("unit conversion", () => {
  it("should convert to miles", () => {
   expect(formatDistance(5000, { unit: "mi" })).toBe("3.11 mi");
  });
 });
});

Test Coverage

• Aim for high coverage
• Test edge cases
• Test error conditions

Commit Standards

Commit Messages

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance

Examples:

feat(maps): add measurement tool
fix(charts): correct elevation calculation
docs: update installation guide

Review Checklist

Before submitting code:

• Code follows style guide
• Functions are documented
• Tests are added/updated
• No linting errors
• No console.log statements
• Error handling in place

---

Next: Module Development →