Development Guidelines for the Go Project

Function Documentation

All functions must be documented clearly and concisely. The documentation should include the function's purpose, the parameters it accepts, and the value it returns. The following documentation format must be followed:

Minimum Documentation Example:

// Function to read the content of a file
// Takes the file path as input and returns the file content as a string or an error if something goes wrong.
func ReadPromptFromFile(filePath string) (string, error) {
	content, err := ioutil.ReadFile(filePath)
	if err != nil {
		return "", fmt.Errorf("error reading the file: %w", err)
	}
	return string(content), nil
}

PascalCase Naming Convention

• All functions, types, and variables should follow the PascalCase naming convention.

• This means that every word in a name should start with an uppercase letter, without underscores between words.

Example:

• Good: ReadPromptFromFile, LargeData

• Bad: read_prompt_from_file, large_data

WebSocket and HTTP Services

• All services should be accessible through both WebSocket and HTTP.

• Exceptions may be allowed but should be justified and explicitly documented in the code.

• Both implementations should be as similar as possible to avoid inconsistencies.

Unit Tests for API Routes

Each route of the API must have a unit test to ensure the functionality works correctly for both HTTP and WebSocket.

• For each route, write a test that checks:

  • HTTP request: Send a request via HTTP and verify the expected response.

  • WebSocket request: Send a request via WebSocket and verify the expected response.

• If both HTTP and WebSocket requests succeed, the test is considered successful.

Line Length Limit

• A line of code should not exceed 100 characters.

• If a line exceeds this limit, create intermediate types to improve readability and maintainability of the code.

Example of creating a type to respect the 100-character line limit:

type LargeData struct {
	Data string
}

func ProcessData(data LargeData) error {
	// Code using the LargeData type
}

File Length Limit

• If a file exceeds 100 lines of code without import/package, it must be split into multiple files for easier management.

• Each file should have a single responsibility, and the file names should be clear and reflect their content.

Terminal Output

• For displaying information in the terminal, use the DisplayContext() function.

• The DisplayContext() function should be documented and used for all terminal outputs to centralize the display logic in the project.

• package utils.

Example of using DisplayContext():

Syntax: 
DisplayContext("message", type, error (optional), exit (boolean, optional))

DisplayContext("Hello world!", Default)  // Display a default message
DisplayContext("Hello world!", Error, err, true)  // Display an error message
DisplayContext("Hello world!", Update)  // Display an update message
DisplayContext("Hello world!", Debug)  // Display a debug message

Error Handling

• Always handle errors explicitly. Do not ignore errors, even if they seem trivial.

• Use fmt.Errorf to wrap errors with context to make debugging easier.

• Return early when an error occurs, and avoid deep nesting of code.

Example:

if err != nil {
    return fmt.Errorf("contextual error: %w", err)
}

Configuration Management

• Configuration should be externalized and not hardcoded in your application.

• Use environment variables for configuration values that differ between environments (e.g., development, staging, production).

• Consider using a configuration management library (e.g., viper) for easier management of settings.