documentation
documentation
c4-model
Understanding the C4 model for software architecture
The C4 model documents software architecture as four zoom levels: Context, Containers, Components, and Code. See how the diagrams work on a concrete example (a paid blog application) and why this hierarchy keeps developers and stakeholders oriented.
typescript
How to simplify TypeScript types and reduce documentation overhead
TypeScript types with many optional fields need comments to explain what goes together. Discriminated unions fix that: split a Task type into per-status variants so invalid combinations fail to compile and the type documents itself. Before and after code included.
Latest
How to set up XML in Grape API
XML support in Grape API takes two steps: register the additional content_type so endpoints accept and return application/xml, then change the root element name of the XML output. Complete Ruby examples built around a products endpoint you can adapt to your API.
Understanding generic types in Typescript
Generic types in TypeScript let one function, class, or interface work safely with many data types. What generics are, how a type parameter beats hardcoding a concrete entity type in a validation helper, and honest pros and cons before you use them everywhere.
Rails optimistic locking, pessimistic locking and how to solve StaleObjectError
Rails locking strategies for concurrent updates: optimistic locking with a lock_version column that works out of the box, pessimistic locking with lock! and with_lock, and practical ways to rescue and resolve the StaleObjectError that optimistic locking raises.
Differences between load, autoload, require, and require_relative in Ruby
Ruby has four ways to load code and each behaves differently: load re-executes a file every time, autoload waits until first use, require loads once from the load path, require_relative resolves from the current file. Examples plus a summary of when to use each.
Ruby in browser via WebAssembly
Ruby 3.2 runs in the browser through WebAssembly: embed Ruby in a script tag with ruby-wasm-wasi or drive the Ruby VM from JavaScript and mix it with HTML. Working examples plus honest limits: no threading or networking, and no extra gems without a custom wasm image.
Solutions for const and enums per class in Ruby
Three ways to define constants and enums per class in Ruby: the ActiveRecord enum macro, a mixed style combining frozen constants with enum, and a dependency-free PORO version. Code for each solution and a comparison to help you pick the right one.
Ruby SOLID in practice with minimizing nesting rule
SOLID in Ruby with working code for every principle: Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion, plus a bonus rule on minimizing nesting and a fair look at the criticisms of SOLID.
Consider using Apipie gem twice
Apipie looks like an easy way to document a Rails API, but check its limits first: no advanced type constraints like exactly_one_of, only partial OpenAPI support, and weak handling of output examples. What to weigh before picking the gem for a larger application.