# Code Style and Conventions Standards for Hetzner

This document outlines the coding style and conventions standards for software development at Hetzner. Adhering to these standards ensures code consistency, readability, maintainability, and collaboration across teams. These guidelines are designed to work with modern tooling, including AI coding assistants.

## 1. General Principles

### 1.1. Consistency

* **Do This:** Follow the established coding style within the project. Inconsistency is more detrimental than any specific style choice.

* **Don't Do This:** Introduce new or conflicting styles without team consensus.

* **Why:** Consistency reduces cognitive load, making code easier to understand and maintain.

### 1.2. Readability

* **Do This:** Write code that is easy to read and understand, even for developers unfamiliar with the codebase.

* **Don't Do This:** Sacrifice readability for minor performance gains.

* **Why:** Readability is crucial for debugging, code review, and long-term maintenance.

### 1.3. Maintainability

* **Do This:** Design code that is easy to modify, extend, and refactor.

* **Don't Do This:** Create tightly coupled or overly complex code that is difficult to change.

* **Why:** Maintainability reduces the cost of ownership over the lifespan of the software.

### 1.4 Self-Documenting Code

* **Do This:** Strive to make your code as self-documenting as possible by using meaningful names for variables, functions, and classes, and by writing clear and concise comments when necessary.

* **Don't Do This:** Assume the reader knows the intent of the code without any indication.

* **Why:** Self-documenting code reduces the need for extensive documentation, making it faster to understand and modify.

## 2. Language-Specific Standards

The following sections detail the specific coding standards for commonly used languages at Hetzner. This document will focus on Python and Go, two prevalent languages in Hetzner's infrastructure and internal tooling.

### 2.1. Python

#### 2.1.1. Formatting (PEP 8)

* **Do This:** Adhere to PEP 8, the style guide for Python code.

* **Don't Do This:** Ignore PEP 8 guidelines.

* **Why:** PEP 8 provides a consistent style guide for Python code, ensuring readability.

* **Indentation:** Use 4 spaces per indentation level.

* **Line Length:** Limit lines to 79 characters for code and 72 characters for docstrings.

* **Blank Lines:** Separate top-level function and class definitions with two blank lines. Separate method definitions inside a class with one blank line.

* **Imports:** Import packages on separate lines, and group imports in the following order: standard library imports, third-party library imports, and local application/library specific imports.

"""python

# Correct

import os

import sys

import requests

from flask import Flask

from my_project import utils

def my_function():

pass

class MyClass:

def __init__(self):

pass

def my_method(self):

pass

# Incorrect

import os, sys # Don't do this

from flask import Flask, request # Don't do this

"""

#### 2.1.2. Naming Conventions

* **Do This:** Use descriptive and meaningful names.

* **Don't Do This:** Use single-letter variable names or cryptic abbreviations (except for loop counters).

* **Why:** Clear names improve code understanding.

* **Variables:** Use "snake_case" for variable names.

* **Functions:** Use "snake_case" for function names.

* **Classes:** Use "CamelCase" for class names.

* **Constants:** Use "UPPER_SNAKE_CASE" for constants.

"""python

# Correct

user_name = "John Doe"

def calculate_average(numbers):

pass

class UserProfile:

pass

MAX_CONNECTIONS = 1000

# Incorrect

u = "John Doe" # Bad variable name

def calc_avg(nums): # Bad function name

pass

class UP: # Bad class name

pass

"""

#### 2.1.3. Docstrings

* **Do This:** Write comprehensive docstrings for all modules, classes, functions, and methods using the reStructuredText format.

* **Don't Do This:** Omit docstrings or write vague and unhelpful docstrings.

* **Why:** Docstrings provide essential documentation for the codebase, which is crucial for understanding the purpose and usage of different components.

"""python

def fetch_data(url: str, timeout: int = 10) -> dict:

"""

Fetches data from the given URL.

:param url: The URL to fetch data from.

:param timeout: The timeout in seconds for the request.

:return: A dictionary containing the fetched data.

:raises requests.exceptions.RequestException: If the request fails.

"""

try:

response = requests.get(url, timeout=timeout)

response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)

return response.json()

except requests.exceptions.RequestException as e:

raise Exception(f"Failed to fetch data from {url}: {e}") from e

"""

#### 2.1.4. Error Handling

* **Do This:** Use try-except blocks to handle exceptions gracefully. Log errors and provide informative error messages. Consider using custom exceptions for application-specific errors at Hetzner.

* **Don't Do This:** Ignore exceptions or use bare "except" clauses.

* **Why:** Proper error handling prevents unexpected crashes and provides valuable debugging information. When dealing with Hetzner's APIs, it’s particularly important to handle rate limiting and service unavailability appropriately.

"""python

import logging

class HetznerAPIError(Exception):

"""Custom exception for Hetzner API errors."""

pass

def provision_server(api_key: str, server_type: str, location: str) -> dict:

"""

Provisions a server using the Hetzner API.

:param api_key: The Hetzner API key.

:param server_type: The type of server to provision.

:param location: The location of the server.

:return: A dictionary containing the server details.

:raises HetznerAPIError: If the API request fails. Includes rate limiting checks.

"""

url = "https://api.hetzner.cloud/v1/servers"

headers = {"Authorization": f"Bearer {api_key}"}

data = {"name": f"server-{server_type}-{location}", "server_type": server_type, "location": location}

try:

response = requests.post(url, headers=headers, json=data)

response.raise_for_status()

# Handle rate limiting

if response.status_code == 429:

logging.warning("Hetzner API rate limit exceeded. Implement retry logic.")

raise HetznerAPIError("Hetzner API rate limit exceeded.")

return response.json()

except requests.exceptions.RequestException as e:

logging.error(f"Failed to provision server: {e}")

raise HetznerAPIError(f"Failed to provision server: {e}") from e

try:

server_details = provision_server("YOUR_API_KEY", "cx11", "fsn1")

print(f"Server provisioned: {server_details}")

except HetznerAPIError as e:

print(f"Error: {e}")

except Exception as e: # Catch any other unforeseen exceptions

logging.exception("An unexpected error occurred during server provisioning.")

"""

#### 2.1.5. Use of Virtual Environments

* **Do This:** Always use virtual environments ("venv") to isolate project dependencies.

* **Don't Do This:** Install packages globally.

* **Why:** Virtual environments prevent dependency conflicts between projects.

"""bash

python3 -m venv .venv

source .venv/bin/activate

pip install requests

"""

#### 2.1.6. Type Hints

* **Do This:** Utilize type hints to improve code clarity and enable static analysis.

* **Don't Do This:** Avoid type hints in new code.

* **Why:** Type hints make code easier to understand and help catch errors early.

"""python

def greet(name: str) -> str:

"""Greets the person passed in as a parameter."""

return f"Hello, {name}"

"""

#### 2.1.7. Logging

* **Do This:** Employ a robust logging strategy that captures significant events and errors. Configure logging levels (DEBUG, INFO, WARNING, ERROR, CRITICAL) to filter messages based on their severity. Use structured logging for easier analysis with tools like Graylog.

* **Don't Do This:** Print raw messages to the console for important events in deployed systems.

* **Why:** Logging facilitates debugging, monitoring, and auditing, giving insights into the application’s behavior and performance within Hetzner infrastructure.

"""python

import logging

# Configure logging

logging.basicConfig(level=logging.INFO,

format='%(asctime)s - %(levelname)s - %(message)s')

def process_data(data: dict):

"""Processes the given data."""

logging.info("Processing data...")

try:

# Simulate some processing

result = data['value'] * 2

logging.debug(f"Processed data: {result}")

return result

except KeyError:

logging.error("Missing 'value' key in data.")

return None

data = {'value': 10}

process_data(data) #logs "Processing data..." and then the debug statement

data_err = {'foo': 10}

process_data(data_err) #logs "Missing 'value' key in data."

"""

#### 2.1.8 Context Managers

* **Do This:** Use context managers ("with" statement) for resource handling (e.g., file operations, database connections).

* **Don't Do This:** Manually open and close resources without using a context manager.

* **Why:** Context managers ensure resources are properly released, even if exceptions occur.

"""python

with open("my_file.txt", "w") as f:

f.write("Hello, world!")

# File is automatically closed after the 'with' block

"""

### 2.2. Go

#### 2.2.1. Formatting (go fmt)

* **Do This:** Run "go fmt" on all Go code before committing.

* **Don't Do This:** Ignore the output of "go fmt".

* **Why:** "go fmt" automatically formats Go code according to the official Go style guide.

"""go

// Correct

package main

import "fmt"

func main() {

fmt.Println("Hello, World!")

}

// Incorrect

package main

import "fmt"

func main() {

fmt.Println("Hello, World!")

}

"""

#### 2.2.2. Naming Conventions

* **Do This:** Follow Go's naming conventions.

* **Don't Do This:** Use inconsistent or unclear names.

* **Why:** Consistent naming makes Go code easier to read and understand.

* **Variables:** Use "camelCase" for variable names (or "snake_case" if interfacing with other systems that commonly use it).

* **Functions:** Use "CamelCase" for function names.

* **Types:** Use "CamelCase" for type names.

* **Constants:** Use "CamelCase" or "UPPER_CASE" for constants.

"""go

// Correct

package main

var userName string

func CalculateAverage(numbers []float64) float64 {

// ...

}

type UserProfile struct {

// ...

}

const MaxConnections = 1000

// Incorrect

package main

var user_name string //use camelCase

func calculate_average(numbers []float64) float64 { //Use CamelCase

// ...

}

"""

#### 2.2.3. Comments

* **Do This:** Write clear and concise comments explaining the purpose of code.

* **Don't Do This:** Write unnecessary or redundant comments.

* **Why:** Comments provide essential context and explain complex logic.

"""go

// CalculateSum returns the sum of the numbers in the given slice.

func CalculateSum(numbers []float64) float64 {

sum := 0.0

for _, number := range numbers {

sum += number

}

return sum

}

"""

#### 2.2.4. Error Handling

* **Do This:** Handle errors explicitly. Return errors as the last return value from a function.

* **Don't Do This:** Ignore errors or use "panic" for non-fatal errors.

* **Why:** Proper error handling prevents unexpected crashes and provides valuable debugging information.

"""go

package main

import (

"fmt"

"errors"

)

func divide(a, b float64) (float64, error) {

if b == 0 {

return 0, errors.New("division by zero")

}

return a / b, nil

}

func main() {

result, err := divide(10, 2)

if err != nil {

fmt.Println("Error:", err)

return

}

fmt.Println("Result:", result)

result, err = divide(10, 0)

if err != nil {

fmt.Println("Error:", err) //This line executes

return

}

fmt.Println("Result:", result)

}

"""

#### 2.2.5. Effective Go

* **Do This:** Follow the guidelines in Effective Go.

* **Don't Do This:** Ignore Go's best practices.

* **Why:** Effective Go provides valuable guidance on writing idiomatic Go code.

#### 2.2.6. Dependency Management (Go Modules)

* **Do This:** Use Go modules for dependency management.

* **Don't Do This:** Use older dependency management tools.

* **Why:** Go modules provide a standardized way to manage dependencies in Go projects.

"""bash

go mod init my_project

go get github.com/gin-gonic/gin

"""

#### 2.2.7. Concurrency

* **Do This:** Use goroutines and channels for concurrent operations. Handle concurrency safely with proper synchronization mechanisms (e.g., mutexes, atomic operations).

* **Don't Do This:** Create race conditions or deadlocks.

* **Why:** Go is designed for concurrency. Correctly utilizing goroutines and channels can improve performance. When working with Hetzner infrastructure, consider goroutines to perform parallel requests to Hetzner APIs.

"""go

package main

import (

"fmt"

"time"

"sync"

)

func worker(id int, wg *sync.WaitGroup) {

defer wg.Done()

fmt.Printf("Worker %d starting\n", id)

time.Sleep(time.Second)

fmt.Printf("Worker %d done\n", id)

}

func main() {

var wg sync.WaitGroup

for i := 1; i <= 5; i++ {

wg.Add(1)

go worker(i, &wg)

}

wg.Wait()

fmt.Println("All workers done")

}

"""

#### 2.2.8. Logging

* **Do This:** Use a logging library (e.g., "logrus", "zap") for structured logging. Configure log levels.

* **Don't Do This:** Use "fmt.Println" for logging in production code.

* **Why:** Structured logging facilitates analysis and monitoring in production environments.

"""go

package main

import (

"time"

"github.com/sirupsen/logrus"

)

var log = logrus.New()

func main() {

// Set the log level

log.SetLevel(logrus.InfoLevel)

// Example log messages

log.WithFields(logrus.Fields{

"animal": "walrus",

"number": 1234,

}).Info("A walrus appears")

log.Warn("This is a warning message")

log.Error("This is an error message")

log.Info("Sleeping for 2 seconds.")

time.Sleep(2 * time.Second) // Simulate some task

log.Info("Finished task.")

}

"""

## 3. Hetzner-Specific Considerations

These standards are essential for maintaining operational consistency when integrating with Hetzner Cloud resources and APIs.

### 3.1. API Integration

* **Do This:** Use official Hetzner SDKs when available. Implement retry logic for transient errors and rate limiting. Use environment variables for API keys and sensitive data.

* **Don't Do This:** Hardcode API keys directly in the source code. Ignore rate limits, leading to service disruption. Fail to handle transient network errors when communicating with the Hetzner API.

* **Why:** Following best practices for API integration ensures reliable and secure access to Hetzner services.

### 3.2. Infrastructure as Code

* **Do This:** Utilize infrastructure-as-code tools like Terraform to provision and manage Hetzner Cloud resources. Define infrastructure configurations in a consistent manner.

* **Don't Do This:** Manually create and manage resources, which can lead to inconsistencies and errors.

* **Why:** Infrastructure as code promotes automation, reproducibility, and version control of infrastructure configurations.

### 3.3. Security

* **Do This:** Follow security best practices for cloud environments. Regularly update software components to patch vulnerabilities. Implement proper access control mechanisms.

* **Don't Do This:** Use default passwords or insecure configurations. Expose sensitive services to the public internet.

* **Why:** Security is paramount for protecting data and infrastructure.

### 3.4. Performance

* **Do This:** Optimize code and configurations for performance. Monitor resource utilization and identify bottlenecks. Use caching effectively to reduce latency.

* **Don't Do This:** Write inefficient code or create overly complex configurations. Neglect monitoring and performance tuning.

* **Why:** Optimized code and configurations improve the responsiveness and scalability of applications.

## 4. Code Review

* **Do This:** Conduct thorough code reviews, focusing on code quality, correctness, and adherence to these standards.

* **Don't Do This:** Skip code reviews or perform superficial reviews.

* **Why:** Code reviews help identify potential problems early and ensure that code meets the required standards.

## 5. Tooling

* **Do This:** Use linters, static analyzers, and formatters to automate code quality checks. Integrate these tools into the development workflow.

* **Don't Do This:** Rely solely on manual code reviews.

* **Why:** Automated tools help enforce coding standards consistently and efficiently. Examples of tools might include "flake8" and "mypy" for Python and "golangci-lint" for Go. Static analysis tools will help catch common errors like nil pointer dereferences or unhandled exceptions.

## 6. Conclusion

Adhering to these coding style and convention standards ensures code consistency, readability, maintainability, and collaboration across teams at Hetzner. Regular reviews and updates to these standards are encouraged to adapt to evolving technologies and best practices. By following these guidelines, Hetzner can ensure that its code remains high-quality, secure, and performant. These guidelines should also be communicated and configured in AI coding assistants to encourage adherence.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Code Style and Conventions Standards for Hetzner

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

API Integration Standards for Hetzner

Testing Methodologies Standards for Hetzner

Component Design Standards for Hetzner

Performance Optimization Standards for Hetzner

Deployment and DevOps Standards for Hetzner