Mindful coding: Purpose and intention

Mindful coding is not about typing with focused breaths or meticulously observing each keystroke. Rather, it concerns the purpose behind the code itself. While programming languages provide a vocabulary for describing actions such as iterating, calling functions, assigning values, or raising exceptions, the real question is often not what the code does, but why. This distinction is easily overlooked due to the apparent mechanics of the code.

Good code fills in this missing context by making the intent of the code clear, not by explaining every single line but by revealing the purpose of the code in a broader operation. One simple way to communicate intent is through meaningful naming. A value of 5 offers little information, but a constant named MAX_RETRIES clearly indicates its role as a limit for an operation.

Naming is often a challenging task, as exemplified by the joke that the hardest problems in computer science are naming things, cache invalidation, and off-by-one errors. Naming becomes even more crucial when it reveals underlying issues with the design. For instance, when extracting code into a function, a struggle to find a suitable name may uncover that the extracted concept lacks coherence or reusability.

The name of a function can also reveal whether an abstraction is too broad. A function named validateAndStore may seem reasonable, but if it simultaneously validates input, stores data, and determines HTTP error responses, it indicates that multiple concerns have been combined. The issue lies not with the name but with the overly comprehensive abstraction.

When faced with naming difficulties, sometimes the solution is not to search for a better word but to step back and ask what concept is being named. If no meaningful concept exists, perhaps the boundary should not exist at all. This distinction applies beyond the code as well. Consider commit messages. While it's common to write messages like "Add validation module" or "Introduce retry logic," these often fail to provide valuable context.

A more useful commit message explains the reasoning behind the change, such as a bug discovery, user failure, or an unexpected implementation breakdown.

Similarly, comments in code serve to explain aspects that cannot be easily deduced from the code itself. For example, if a piece of code appears strange due to a prior bug, a comment can preserve that context, helping future readers understand the purpose behind seemingly arbitrary code. Ultimately, mindful coding emphasizes being conscious of the information your code communicates, as this reasoning often proves more useful to future readers than additional comments, longer names, or elaborate abstractions.