Skip to content

Latest commit

 

History

History
426 lines (314 loc) · 17.3 KB

STYLEGUIDE.md

File metadata and controls

426 lines (314 loc) · 17.3 KB

Style Guide

This document outlines the style guide for Jekwwer/pgsql-workspace. It covers commit message formatting, coding conventions, repository structure, and other aspects detailed in Scope. Adhering to these guidelines ensures a consistent and readable project.

Introduction

Purpose

This guide standardizes coding and documentation practices to ensure consistency, enhance readability, and support effective collaboration.

Audience

This style guide is intended for:

  • Developers and Contributors: Those writing code or documentation for the project.
  • Maintainers: Individuals responsible for reviewing and merging contributions.
  • Reviewers: Participants in code reviews to ensure adherence to standards.

Scope

This document covers:

  • Repository Structure: Directory layout, file naming conventions, and configuration file details.
  • Naming Conventions: Standards for variables, constants, functions, and file/directory names.
  • Code Formatting and Style: Guidelines on indentation, line length, brace styles, comments, EditorConfig settings, and linting/formatting tools.
  • Documentation: Standards for creating and maintaining project documentation.
  • Additional Best Practices: Other practices to improve overall code quality and project maintainability.

Project Overview

Project Goals

This repository provides a ready-to-use development environment for PostgreSQL, leveraging devcontainer technology and GitHub Codespaces with VS Code.

Technology Stack

Uses VS Code configurations, a devcontainer setup, essential extensions and configuration files.

Target Audience

Developers who need a streamlined workspace template for PostgreSQL development.

Repository Structure

Directory Layout

/ (root)                                # repository root
├── .devcontainer                       ├── # devcontainer-related configurations
│   └── devcontainer.json               │   └── # devcontainer setup
├── .github                             ├── # GitHub-related configurations
│   ├── ISSUE_TEMPLATE                  │   ├── # issue templates
│   │   └── *                           │   │   └── # all files in the folder
│   ├── PULL_REQUEST_TEMPLATE           │   ├── # pull request templates
│   │   └── *                           │   │   └── # all files in the folder
│   ├── workflows                       │   ├── # GitHub workflows
│   │   └── release.yml                 │   │   └── # release workflow
│   ├── dependabot.yml                  │   ├── # Dependabot configuration
│   ├── FUNDING.yml                     │   ├── # funding configuration
│   └── PULL_REQUEST_TEMPLATE.md        │   ├── # default pull request template
├── scripts                             ├── # utility scripts
│   └── start.sh                        │   └── # script to initialize the development environment
├── sql                                 ├── # SQL files and database scripts
│   └── hello_world.sql                 │   └── # sample SQL file demonstrating basic queries
├── .editorconfig                       ├── # editor configuration
├── .gitignore                          ├── # files to ignore in Git
├── .markdownlint.json                  ├── # markdown linting configuration
├── .pre-commit-config.yaml             ├── # pre-commit hook configuration
├── .prettierrc                         ├── # Prettier configuration
├── .releaserc.js                       ├── # semantic release configuration
├── .sqlfluff                           ├── # SQLFluff configuration for SQL linting
├── CHANGELOG.md                        ├── # changelog
├── CODE_OF_CONDUCT.md                  ├── # code of conduct
├── CONTRIBUTING.md                     ├── # contributing guidelines
├── cspell.json                         ├── # spell checking configuration
├── docker-compose.yml                  ├── # Docker Compose configuration (PostgreSQL service)
├── LICENSE                             ├── # main license
├── package-lock.json                   ├── # npm lock file
├── package.json                        ├── # npm package configuration
├── README.md                           ├── # project README
├── requirements.txt                    ├── # pip dependencies
├── SECURITY.md                         ├── # security information
└── STYLEGUIDE.md                       └── # style guide

File Naming Conventions

  • Documentation Files: Key documentation files (e.g., CODE_OF_CONDUCT.md, CONTRIBUTING.md, README.md, SECURITY.md) are named using SCREAMING_SNAKE_CASE.

  • Configuration Files: Tool configuration files (e.g., cspell.json, .editorconfig, .pre-commit-config.yaml,.prettierrc) use lowercase naming, following the specific requirements of each tool.

  • Scripts: Executable scripts are named in lowercase, typically using snake_case for clarity and consistency.

  • GitHub and Workflow Files: Files within the .github directory—such as dependabot.yml, FUNDING.yml, and templates under ISSUE_TEMPLATE/PULL_REQUEST_TEMPLATE follow GitHub's naming conventions. This may include a mix of uppercase (e.g., BUG_REPORT.md) and lowercase (e.g., config.yml) filenames to ensure proper GitHub integration. In the .github/workflows/ directory, YAML files for GitHub Actions are recommended to use kebab-case (e.g., deploy-app.yml, run-tests.yml), aligning with GitHub's documentation and best practices.

Directory Naming Conventions

  • General Naming: Use lowercase letters for directory names. For multi-word names, use kebab-case (e.g., node-modules, source-files). Choose names that clearly indicate the directory's content or purpose (e.g., docs for documentation, assets for media).

  • Special Directories: Directories prefixed with a dot (e.g., .github, .devcontainer) have specific roles and should remain unchanged.

Configuration Files

Key configuration files in the repository:

  • .devcontainer/devcontainer.json: Development container setup, including VS Code settings, environment variables, and extensions.
  • .gitignore: Files and directories excluded from version control.
  • .editorconfig: Coding style settings across different editors.
  • .markdownlint.json: Markdown linting rules and exclusions.
  • .pre-commit-config.yaml: Pre-commit hooks.
  • .prettierrc: Formatting rules.
  • .releaserc.js: Semantic release process and versioning.
  • .sqlfluff: SQLFluff configuration for linting SQL files.
  • cspell.json: Spelling rules for consistency.
  • docker-compose.yml: Docker services, primarily PostgreSQL service.
  • package.json: Project metadata, scripts, and dependency definitions.
  • package-lock.json: Locked dependency versions for consistent installations.
  • requirements.txt: Python dependencies.

Naming Conventions

General Guidelines

Keep names descriptive and consistent. Stick to language-specific conventions to maintain clarity across the project.

Variables

  • SQL: Use snake_case for identifiers (e.g., user_id).

Functions/Methods

  • SQL: Use snake_case for functions (e.g., calculate_total()).

Keywords

  • SQL: Always use uppercase for SQL keywords (e.g., SELECT, FROM, WHERE) following PostgreSQL standards.

Files

See File Naming Conventions.

Code Formatting and Style

The project adheres to the rules specified in the .editorconfig, .markdownlint.json, .prettierrc, and .sqlfluff configuration files.

Indentation and Spacing

  • General Guidelines: Use 2 spaces per indentation level throughout the project. Tabs are not permitted. (Enforced by EditorConfig)
  • SQL: Use 4 spaces per indentation level for SQL files. (Enforced by both EditorConfig and SQLFluff)

Line Length

  • Code Files: Limit lines to 88 characters. (Enforced by Prettier for supported files and yamllint pre-commit hook for .yaml/.yml files)
  • Markdown: Allow up to 120 characters per line. (Enforced by Prettier and markdownlint pre-commit)
  • SQL: Allow up to 120 characters per line. (Enforced by SQLFluff)

Braces and Control Structures

  • SQL: SQL syntax does not use braces; instead, rely on consistent indentation and clear structure. For PL/pgSQL or other procedural code, use BEGIN and END to delimit code blocks and ensure keywords (e.g., IF, ELSE, LOOP) are clearly aligned.

Comments and Documentation

  • General Guidance: All comments should enhance clarity and avoid redundancy with well-named functions and variables. Ensure comments do not exceed the maximum line length.

  • Inline Comments: Place concise inline comments on the same line or immediately above the code they describe.

  • Block Comments: Use block comments for extended explanations.

  • File Header Comments: Every file should begin with a header comment (except for files in .json, .md, and LICENSE) that provides a short, third-person description of the file's purpose. For example:

    # .pre-commit-config.yaml: Sets up pre-commit hooks to automate code quality checks.

If a file starts with a shebang (e.g., #!/bin/bash), place the header comment on the line immediately following the shebang.

EditorConfig

  • Purpose: The .editorconfig file ensures consistent coding styles across all editors by specifying:
    • Indentation: 2 spaces (4 spaces for SQL files)
    • Line Endings: Unix-style (lf)
    • Charset: UTF-8
    • Max Line Length: 88 for code, 120 for Markdown/SQL (Note: .editorconfig provides these values for reference; enforcement is handled by other tools.)
    • Final Newline: Enforced
    • Trailing Whitespace: Trimmed (with specified exceptions)
  • Note: Contributors should use an editor that supports EditorConfig to automatically apply these settings.

Prettier

  • Purpose: The .prettierrc file defines the project's code formatting rules for Prettier-supported files, ensuring a consistent style across various file types by specifying:
    • Semicolons: Enabled
    • Quote Style: Single quotes preferred
    • Trailing Commas: Added where possible
    • Tab Width: 2 spaces (tabs are not used)
    • End of Line: Unix-style (lf)
    • Print Width: 88 characters (Note: Overrides are applied for Markdown files with a print width of 120, while JSON files have no enforced limit.)
  • Note: Prettier is integrated as an auto-formatter in VS Code and runs as part of a pre-commit hook to automatically format code before commits.

SQLFluff

  • Purpose: The .sqlfluff file defines the project's code formatting rules for SQL files by specifying:
    • Capitalization Policy: upper
    • Error Handling: Error AM04 (Query produces an unknown number of result columns) is set as a warning
    • Tab Width: 4 spaces
    • Print Width: 120 characters (Note: Overrides are applied for Markdown files with a print width of 120, while JSON files have no enforced limit.)
  • Note: SQLFluff is integrated as an auto-formatter in VS Code and runs as part of a pre-commit hook to automatically format SQL code before commits.

Additional Linting and Formatting Tools

  • Pre-commit Hooks: The project leverages pre-commit hooks to enforce code quality through automated checks. Key tools integrated via pre-commit include:
    • pre-commit-hooks: Ensures proper AST parsing, fixes line endings and trailing whitespace, manages mixed line endings, detects private keys, validates YAML and JSON syntax, checks for merge conflicts, detects case conflicts, verifies executable shebangs, fixes formatting, and sorts requirements.txt.
    • markdownlint-cli & markdown-link-check: Enforce the style guide rules for Markdown files and validate links.
    • yamllint: Enforces style guide rules for YAML files.

Documentation

Inline Documentation

See Comments and Documentation.

External Documentation

  • Repository Documentation: The root-level README.md offers an overview of the project and a preview of its appearance on the profile. Additional key documents such as CONTRIBUTING.md, STYLEGUIDE.md, SECURITY.md, and LICENSE are also maintained at the repository root.

Note: File and directory names referenced in Markdown should always be formatted using backticks, for example:

The `.sqlfluff` file defines the project's code formatting rules for SQL files.

Markdown References

  • Reference-Style Links: Use reference-style links for clarity. For example:

    [info][link]

[link]: https://example.com

  • Local References: For links to repository-related documents (e.g., CONTRIBUTING.md or CODE_OF_CONDUCT.md) or internal sections, use SCREAMING_SNAKE_CASE for link identifiers and omit the file extension for documents. For example:

    See [Code of Conduct][CODE_OF_CONDUCT].

[CODE_OF_CONDUCT]: CODE_OF_CONDUCT.md

    And for internal sections:

    See [File Naming Conventions][FILE_NAMING_CONVENTIONS].

[FILE_NAMING_CONVENTIONS]: #file-naming-conventions

    Note: Local references should always appear at the top and be sorted alphabetically. For example:

    [FILE_NAMING_CONVENTIONS]: #file-naming-conventions
[SECURITY]: SECURITY.md
[external-link]: https://example.com

  • External Links: For links that reference external resources, use kebab-case for link identifiers. For example:

    [info][external-link]

[external-link]: https://example.com

    Note: External references should be sorted alphabetically and always appear below local references. For example:

    [SECURITY]: SECURITY.md
[external-link]: https://example.com

Documentation Tools and Best Practices

Tools

  • cspell: A spellchecker tailored for code and Markdown files. It runs as a pre-commit hook and can also be executed via the npm script npm run spell:check.

  • markdown-link-check: Validates hyperlinks within Markdown files and runs as a pre-commit hook.

  • markdownlint: Enforces consistent style and formatting in Markdown documents. It runs as a pre-commit hook.

Consistency and Updates

  • Update documentation alongside code changes.
  • Contributors should update docs when introducing new features or modifying existing functionality.

Style and Tone

  • Maintain a semi-formal tone appropriate for a tech-oriented audience.
  • Use clear, precise language and consistent formatting throughout.

Contribution Guidelines

  • Documentation contributions follow the same process as code changes—submit pull requests for review according to the contribution guidelines.

Additional Best Practices

Security and Privacy

  • Avoid exposing sensitive information in logs or error messages.
  • Regularly review dependencies for security vulnerabilities.

Error Handling and Logging

  • Implement robust error handling to manage unexpected issues gracefully.
  • Use structured logging to capture context without exposing sensitive data.

Code Organization and Maintenance

  • Keep the codebase clean and modular to facilitate understanding and future extensions.
  • Regularly review and refactor code to eliminate redundancy.
  • Use design patterns where appropriate to improve clarity and reusability.

Conclusion

Continuous Improvement

This document is a living resource that should evolve with the project. As new best practices emerge or project requirements change, please update the guide to keep it relevant and effective.

Feedback and Updates

Your input is valuable. If you have suggestions for improvements, clarifications, or additional guidelines, please reach out to the maintainers or submit an issue. For contributing guidelines, refer to CONTRIBUTING.md; for security concerns, see SECURITY.md; for discussions, consult the project's discussion board or contact the project owner at evgenii.shiliaev@jekwwer.com.

This document is based on a template by Evgenii Shiliaev, licensed under CC BY 4.0. All additional content is licensed under LICENSE.