Coding conventions and style guidelines for Go and TypeScript in Burning Ash Protocol.

Code Style Guide

This document outlines coding conventions for BAP.

Go (Backend)

Formatting

Use go fmt for formatting
Run before committing

go fmt ./...

Naming

Type	Convention	Example
Packages	lowercase	`handler`, `repository`
Functions	PascalCase	`GetUser()`, `CreateWill()`
Variables	camelCase	`userID`, `willStatus`
Constants	PascalCase	`MaxFileSize`
Interfaces	PascalCase + er	`Reader`, `Writer`

File Structure

package handler

import (
    "context"
    "net/http"

    "github.com/baprotocol/bap/internal/service"
)

func HandleSomething(svc *service.Service) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // Handler logic
    }
}

Error Handling

Return errors, don't panic
Wrap errors with context

// Good
if err != nil {
    return fmt.Errorf("failed to get user: %w", err)
}

// Bad
if err != nil {
    panic("failed to get user")
}

HTTP Handlers

Use handler structs with dependencies
Return structured errors

type Handler struct {
    DB       *sql.DB
    Services *services.Container
}

func (h *Handler) GetWill(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    willID := chi.URLParam(r, "id")

    will, err := h.Services.Will.Get(ctx, willID)
    if err != nil {
        http.Error(w, err.Error(), http.StatusNotFound)
        return
    }

    respond(w, will)
}

Context Usage

Pass context through call chain
Use context values for request-scoped data

func (s *Service) GetUser(ctx context.Context, id string) (*User, error) {
    // Context used for timeout, cancellation
}

TypeScript/React (Frontend)

Formatting

Use Prettier
Run before committing

npm run format

Naming

Type	Convention	Example
Components	PascalCase	`WillStatus.tsx`
Functions	camelCase	`getWill()`
Variables	camelCase	`willStatus`
Constants	PascalCase	`MAX_FILE_SIZE`
Hooks	camelCase with use	`useWill()`

Components

// Functional component with TypeScript
interface WillCardProps {
    will: Will;
    onDelete: (id: string) => void;
}

export function WillCard({ will, onDelete }: WillCardProps) {
    return (
        <Card>
            <CardHeader>{will.name}</CardHeader>
            <CardContent>
                Status: {will.status}
            </CardContent>
        </Card>
    );
}

Hooks

// Custom hook
export function useWill(willId: string) {
    const [will, setWill] = useState<Will | null>(null);
    const [isLoading, setIsLoading] = useState(true);

    useEffect(() => {
        fetchWill(willId)
            .then(setWill)
            .finally(() => setIsLoading(false));
    }, [willId]);

    return { will, isLoading };
}

API Calls

// API client
import { api } from '@/lib/api';

export async function fetchWill(id: string): Promise<Will> {
    const response = await api.get(`/will/${id}`);
    return response.data;
}

Git Conventions

Commit Messages

type(scope): description

Types: feat, fix, docs, style, refactor, test, chore

Examples:
feat(auth): add JWT refresh endpoint
fix(will): resolve encryption failure
docs(api): update endpoint documentation

Branch Naming

type/description

Examples:
feature/add-survivor
fix/liveness-timeout
docs/api-reference

Testing

Go

func TestGetWill(t *testing.T) {
    // Setup
    svc := &Service{db: testDB}

    // Test
    will, err := svc.GetWill(context.Background(), "123")

    // Assert
    assert.NoError(t, err)
    assert.Equal(t, "123", will.ID)
}

TypeScript

describe('WillCard', () => {
    it('renders will name', () => {
        render(<WillCard will={mockWill} onDelete={fn} />);
        expect(screen.getByText(mockWill.name)).toBeInTheDocument();
    });
});

Documentation

Comments

Document public functions
Use Go doc comments

// GetWill retrieves a will by ID.
// Returns ErrWillNotFound if not found.
func (s *Service) GetWill(ctx context.Context, id string) (*Will, error) {
}

README

Update for significant changes
Keep examples working

Next Steps

Pull Requests — Contribution workflow
Security Reporting — Vulnerability reporting
Development Setup — Local setup

Code Style Guide

On this page