Presetter Style Guidelines

Enforce coding conventions from the alvis/presetter project: American English, lowercase JSDoc comments with action verbs, minimal explanatory comments, and Vitest testing standards.

Instructions

Follow these guidelines when writing code in the presetter codebase or projects using presetter conventions.

1. Language Convention

2. JSDoc Comments

Apply these rules to all JSDoc documentation:

**Good Example:**

```typescript

/** merges two configuration objects */

function merge(target: object, source: object): object { }

```

**Avoid:**

```typescript

/**

* Merges two configuration objects.

*/

function merge(target: object, source: object): object { }

```

**Complete Example with Parameters:**

```typescript

/**

* merges two configuration objects

* @param target the target configuration object

* @param source the source configuration object

* @returns the merged configuration object

* @throws TypeError if either argument is not an object

*/

function merge(target: object, source: object): object {

if (typeof target !== 'object' || typeof source !== 'object') {

throw new TypeError('both target and source must be objects');

}

// implementation...

}

```

3. Explanatory Comments

```typescript

// NOTE:

// this function performs a deep merge of two objects

// it recursively merges nested objects

```

**Good Comment:**

```typescript

// check if user exists before proceeding

if (!user) throw new Error("User not found");

```

**Unnecessary Comment:**

```typescript

// loop through the array

for (let i = 0; i < arr.length; i++) {...}

```

4. Interface Documentation

**Example:**

```typescript

/** describes a product */

interface Product {

// metadata //

/** unique identifier */

id: number;

// details //

/** product name */

name: string;

/** product price */

price: number;

}

```

5. Testing with Vitest

Follow these testing conventions:

**File Naming:**

**Test Isolation:**

**Test Descriptions:**

- `fn:` for function tests

- `op:` for operation tests

- `cl:` for class tests

- `ty:` for utility type tests

**Example:**

```typescript

import { describe, it, expect } from 'vitest';

describe('fn:merge', () => {

it('should merge two flat objects correctly', () => {

const target = { a: 1, b: 2 };

const source = { b: 3, c: 4 };

const result = merge(target, source);

const expected = { a: 1, b: 3, c: 4 };

expect(result).toEqual(expected);

});

it('should perform a deep merge of nested objects', () => {

const target = { a: { b: 1 } };

const source = { a: { c: 2 } };

const result = merge(target, source);

const expected = { a: { b: 1, c: 2 } };

expect(result).toEqual(expected);

});

});

```

Key Takeaways