Error Handling rules

Configure your application not to display detailed error messages (stack traces, PHP warnings) to end users in production. Instead, log errors for developers and show a generic message to users.

Ensure that all caught exceptions are either logged or handled properly. Empty catch blocks are not allowed.

Detect occurrences of the 'with' statement. This construct is banned in strict mode due to unpredictable behavior and makes debugging harder.

Identify functions that raise exceptions but do not document them in docstrings. Missing exception documentation makes it difficult to understand failure cases. Suggest adding an `:raises` section in the docstring.

Never compare the address of a variable to nil (e.g., `&x == nil`). To check if a pointer is nil, compare the pointer itself to nil. The address of a variable (`&x`) will always be non-nil if `x` exists.

Reserve `panic` for unrecoverable situations (like invariant violations or truly fatal errors). For expected error conditions (file not found, invalid input, etc.), return an `error` to the caller instead of panicking.

Check if the `__all__` list in a module contains titles that are not defined. Listing undefined titles can cause `ImportError` when performing wildcard imports.

Verify that `__init__` methods always return `None`. Returning any other value causes a `TypeError` and prevents correct object instantiation.

Identify function calls where the number of arguments passed does not match the expected parameters. This often results in a `TypeError`. Suggest reviewing function signatures.

Detect functions that mix `return` statements with values and those without. Inconsistent return usage can lead to unpredictable behavior.

Verify that special methods (e.g., `__eq__`, `__len__`) have the correct number of parameters. Incorrect parameters can cause runtime errors or unexpected behavior.

Check if resources such as files or database connections are properly closed in a `finally` block. This ensures resources are always released, even if an exception occurs.

Rescue RecordNotFound and return 404 (or domain-appropriate response) instead of 500.

Every awaited async operation must be guarded with error handling. Use try/catch for await and .catch for promise chains; never leave rejections unhandled.

Attach exceptionally/handle to CompletableFuture chains; never assume success.

Catch and map DB exceptions (e.g., SQLIntegrityConstraintViolationException) to domain results; always close resources with use { }.

Use transactions for multi-step writes; on Throwable, rollback and rethrow with context.

Never silently ignore an error, and avoid handling an error (e.g., logging it) and then still returning it. Either handle the error fully or propagate it upward, but not both.

Guard file IO with try/except; handle OSError and data parse errors with clear messages.

Use JSON_THROW_ON_ERROR (PHP ≥7.3) and wrap json_encode/json_decode in try/catch; validate the decoded shape.

Wrap multi-step writes in a transaction; on failure, roll back and rethrow with context.

Use the 'comma, ok' idiom for type assertions to safely handle cases when the assertion fails. Only use a single-value type assertion (which panics on failure) if you are absolutely sure (by prior checks or program logic) that the interface holds the correct type.

Detect transient vs non-transient DB errors; add context and apply retry policies only where safe (idempotent reads/operations).

Error logs must include the operation name and relevant identifiers as structured fields, not just a message string.