/Best Practices

In Praise Of Small Pull Requests

- Elliotte Rusty Harold tl;dr: “Prefer small, focused pull requests that do exactly one thing each. Why?” (1) Easier to review (2) Can be reviewed quickly. (3) Easier to figure out exactly where the mistake is. (4) Less likely to conflict with other developers’ work. (5) Saves a lot of work if you made a critical error. (6) Easier to make sure each individual pull request is completely tested.

featured in #533

Formal Methods: Just Good Engineering Practice?

- Marc Brooker tl;dr: “Earlier this week, I did the keynote at TLA+ conf 2024. My message in the keynote was something I have believed to be true for a long time: formal methods are an important part of good software engineering practice. If you’re a software engineer, especially one working on large-scale systems, distributed systems, or critical low-level system, and are not using formal methods as part of your approach, you’re probably wasting time and money.”

featured in #526

Good Code Is Rarely Read

- Alex Molas tl;dr: “Good code is rarely read. Good code is so ergonomic that you almost don’t need to read it; you just use it. It allows developers to focus on building features and solving problems rather than deciphering existing code. This is the ultimate goal of good coding practices: to create code that is so clear and intuitive that it almost disappears, allowing the functionality to shine through.”

featured in #524

Don’t Refactor Like Uncle Bob. Please

tl;dr: The author critiques an example refactoring from "Clean Code" by Robert Martin, arguing that Martin's changes introduce unnecessary complexity and side effects. The original function is split into a stateful class with unclear naming and fragmented logic. The author provides alternative refactorings that aim for simplicity and clarity over dogmatic adherence to certain principles.

featured in #524

Don’t Refactor Like Uncle Bob. Please

tl;dr: The author critiques an example refactoring from "Clean Code" by Robert Martin, arguing that Martin's changes introduce unnecessary complexity and side effects. The original function is split into a stateful class with unclear naming and fragmented logic. The author provides alternative refactorings that aim for simplicity and clarity over dogmatic adherence to certain principles.

featured in #523

Logging Practices I Follow

- Eliran Turgeman tl;dr: "There are many pitfall that can lead to useless, wasteful and confusing logs. Therefore I follow a specific set of practices which allows me to write better logs while also being consistent across the system." Eliran discusses here. 

featured in #522

Logging Practices I Follow

- Eliran Turgeman tl;dr: "There are many pitfall that can lead to useless, wasteful and confusing logs. Therefore I follow a specific set of practices which allows me to write better logs while also being consistent across the system." Eliran discusses here. 

featured in #521

Don't DRY Your Code Prematurely

- Dan Maksimovich tl;dr: “Many of us have been told the virtues of “Don’t Repeat Yourself” or DRY. Pause and consider: Is the duplication truly redundant or will the functionality need to evolve independently over time? Applying DRY principles too rigidly leads to premature abstractions that make future changes more complex than necessary.”

featured in #519

How To Read Error Messages

- Simon Tatham tl;dr: “There’s a lot of juice to be squeezed out of error messages if you know what to look for. It’s worth learning the skill of extracting all the detailed information you can. That gives you a head start on debugging problems yourself, and a better chance of writing a good bug report for somebody else – and perhaps even a better chance of deciding which of those things to do. In this article, I’ll try to give an overview of the kind of things you can tell from the details of an error message – right down to things as trivial as the punctuation.”

featured in #518

Prefer Noun-Adjective Naming

- Kyle Shevlin tl;dr: Kyle uses noun-adjective naming for components, e.g., StreamCreated instead of CreatedStream. This keeps related components together alphabetically in directories and makes them easier to search for. It's a small change but can lead to better organization in a codebase.

featured in #517