style-guide

Varlock Documentation and Codebase Style Guide

description: | This rule establishes standards for writing and editing documentation, comments, and prose in the Varlock codebase. It aims to ensure clarity, professionalism, and consistency across all written materials, including READMEs, guides, and inline documentation.

filters:

Applies to all Markdown, MDX, and documentation files

• type: file_extension pattern: ".(md|mdx|mdc)$"

Applies to docstring and comment blocks in code

• type: content pattern: "(?s)(/*.?*/|//.?$|#.*?$)"

actions:

• type: suggest message: | When writing or editing documentation, comments, or prose:

  1. Clarity and Conciseness

     • Use clear, direct language. Avoid unnecessary words or repetition.
     • Prefer active voice and short sentences.
     • Avoid redundancy (e.g., do not restate the same point in different ways).

  2. Professional and Consistent Tone

     • Maintain a professional, helpful, and neutral tone.
     • Use consistent terminology for technical concepts (e.g., "environment flag," "environment-specific file").
     • Use standard terms for configuration, environment variables, and deployment concepts.

  3. Grammar and Punctuation

     • Use correct grammar and spelling throughout.
     • End all bullet points with a period or none, but be consistent within each list.
     • Use en dashes (–) for ranges or parenthetical statements, not hyphens (-).
     • Use American English spelling unless otherwise specified.

  4. Formatting and Structure

     • Separate code blocks and prose clearly. Do not embed explanations within code blocks.
     • Use Markdown formatting for emphasis, lists, and headings.
     • For lists, use consistent bullet or numbering style. Indent nested lists properly.
     • Use italics or bold for emphasis, but avoid overuse.

  5. Technical Accuracy

     • Use correct and up-to-date technical terms (e.g., "IntelliSense" not "intellisense").
     • Reference official documentation for third-party tools or platforms when possible.
     • When describing configuration, use the exact variable or file names as they appear in code.

  6. Examples and Code

     • Place code examples in fenced code blocks with the appropriate language tag.
     • Do not alter code examples for style unless correcting an error or inconsistency.
     • Keep code and prose separate; do not mix explanations into code blocks.

  7. Environment and Configuration Concepts

     • Use "environment flag" for the concept controlling which environment-specific files are loaded.
     • Use "environment-specific file" for files like .env.development, .env.production, etc.
     • Use "non-sensitive" and "sensitive" for configuration values, and explain the criteria for each.

  8. Warnings and Notes

     • Use blockquotes (>) for warnings, notes, and tips. Start with "NOTE –", "TIP –", or "WARNING –" as appropriate.
     • Be concise and direct in warnings and notes.

examples:

• input: | You need to make sure to tell your package manager to override all the resolution of @next/env with @varlock/nextjs-integration, otherwise it won't work right. output: | You must tell your package manager to override all resolutions of @next/env with @varlock/nextjs-integration.

• input: | While .env.schema, .env, and .env.local will always be loaded, loading env-specific files is controlled by a thing called an environment flag, which you can set however you want. output: | While .env.schema, .env, and .env.local will always be loaded, loading environment-specific files is controlled by the concept of an 'environment flag.'

• input: | NOTE - All non sensitive items will be bundled at build time via varlock's ENV object, but process.env replacements will only include NEXT_PUBLIC_ prefixed items. (be careful!) output: | NOTE – All non-sensitive items will be bundled at build time via varlock's ENV object, while process.env replacements will only include NEXT_PUBLIC_-prefixed items.