Code Examples Guidelines

This document provides guidelines for creating and maintaining code examples in the DeepLint documentation. Following these guidelines ensures that code examples are consistent, clean, and helpful for users.

General Principles

Clean Code

Code examples should follow the clean code principles and be self-explanatory whenever possible. This means:

• Use descriptive variable and function names

• Keep functions small and focused

• Follow consistent formatting

• Avoid unnecessary complexity

Minimal Examples

Examples should be minimal and focused on illustrating a specific concept or feature. Remove any code that isn't directly relevant to what you're demonstrating.

Real-World Relevance

While examples should be minimal, they should also be realistic and demonstrate practical use cases that users might encounter.

Comments in Code Examples

When to Use Comments

Comments in code examples should be used sparingly and only when they add value:

• Use comments to explain "why", not "what" or "how"

• Use comments to highlight important concepts that might not be immediately obvious

• Use comments to indicate where code has been omitted for brevity

When to Avoid Comments

Avoid comments that:

• Simply restate what the code is doing

• Could be made unnecessary by using better variable or function names

• Explain basic programming concepts that the target audience should already understand

• Are outdated or incorrect

Comment Style

When comments are necessary:

• Keep them brief and to the point

• Use consistent style (e.g., // Comment for single-line comments)

• For multi-line comments, use // Comment line 1 and // Comment line 2 rather than /* ... */

• Place comments on their own line before the code they describe, not at the end of lines

Examples

Example 1: Unnecessary Comments

// ❌ Bad: Unnecessary comments
// Create a new context builder
const contextBuilder = new ContextBuilder();

// Build the context
const result = await contextBuilder.buildContext();

// Log the result
console.log(`Built context with ${result.stats.totalTokens} tokens`);

Example 2: Better Without Comments

// ✅ Good: Self-explanatory code without unnecessary comments
const contextBuilder = new ContextBuilder();
const result = await contextBuilder.buildContext();
console.log(`Built context with ${result.stats.totalTokens} tokens`);

Example 3: Appropriate Comments

// ✅ Good: Comments that add value
// Configure the context builder with custom options
const contextBuilder = new ContextBuilder({
  contextType: "deep",
  maxTokens: 16000, // Increased token limit for larger codebases
  includeDependencies: true,
});

// Process only specific files instead of all staged changes
const result = await contextBuilder.buildContextForFiles(["src/main.ts", "src/utils.ts"]);

// ... rest of implementation omitted for brevity

Example 4: JSDoc Comments

/**
 * Builds context for LLM analysis based on staged changes
 *
 * @param options - Options for the context builder
 * @returns Promise resolving to the context build result
 * @throws {GitError} If Git operations fail
 */
async function buildContext(
  options?: Partial<ContextBuilderOptions>,
): Promise<ContextBuildResult> {
  const contextBuilder = new ContextBuilder(options);
  return contextBuilder.buildContext();
}

Best Practices for Different Types of Code Examples

Command Line Examples

For command line examples:

• Use comments to explain the purpose of commands

• Include expected output when relevant

• Use # for comments in bash code blocks

# Initialize DeepLint with YAML configuration
$ deeplint init --yaml

# Output:
# DeepLint initialized successfully!
# Configuration file created at: .deeplintrc.yml

Configuration Examples

For configuration examples:

• Use comments to explain non-obvious options

• Include only relevant configuration sections

• Show both JavaScript and YAML examples when applicable

// JavaScript configuration example
export default defineConfig({
  contextBuilder: {
    contextType: "light",
    maxTokens: 8000, // Adjust based on your codebase size
    includeDependencies: false, // Set to true for deeper analysis
  },
  // Other configuration sections omitted for brevity
});

API Usage Examples

For API usage examples:

• Focus on the specific API being documented

• Include error handling when relevant

• Show complete, working examples

// Example of using the ContextBuilder API
import { ContextBuilder } from "deeplint";

async function analyzeCode() {
  try {
    const contextBuilder = new ContextBuilder();
    const result = await contextBuilder.buildContext();

    console.log(`Analysis complete: ${result.stats.changedFiles} files analyzed`);
    console.log(`Total tokens: ${result.stats.totalTokens}`);

    return result;
  } catch (error) {
    console.error(`Analysis failed: ${error.message}`);
    throw error;
  }
}

Implementation Guidelines

When implementing these guidelines:

1. Review existing documentation for unnecessary comments in code examples

2. Prioritize user-facing documentation (Getting Started guides, README, etc.)

3. Be consistent across all documentation

4. Test code examples to ensure they work as expected

5. Update examples when the API or behavior changes

Checklist for Code Examples

Use this checklist when creating or reviewing code examples:

• Does the example follow the project's coding standards?

• Is the example minimal and focused on the concept being illustrated?

• Are variable and function names descriptive and self-explanatory?

• Are comments used only when necessary to explain "why" or highlight important concepts?

• Are there any unnecessary comments that could be removed?

• Is the example realistic and practical?

• Has the example been tested to ensure it works as expected?

• Is the example consistent with other examples in the documentation?

Conclusion

By following these guidelines, we can ensure that code examples in the DeepLint documentation are clean, consistent, and helpful for users. Remember that the goal of code examples is to illustrate concepts and features in a way that is easy to understand and apply.