Best Practices for Commenting Code

code comments

I often hear that we need more and better comments in the code we write. In my experience, we often need better comments, we rarely need more, and often we need less. Before you crucify me for my sacrilege, let me explain. #1 – Incorrect Comments Incorrect documentation is worse than no documentation, and redundant …

Read more

Practical Patterns for Technical Writing

Practical Patterns for Techincal Writing

Writing technical documents like API or architectural documentation which exceeds a simple flow diagram can be a daunting task. If you have some experience with technical documents, you will probably agree that there is nothing more frustrating than bad documentation. Lately, technical writing has become a more important part of my job, so I put …

Read more

How to Make Pure Functions in Golang

Pure Functions in Go

Pure functions are often hyped up in the JavaScript world, probably because of the abundance of stateful front end applications. While pure functions have their downsides (i.e. inconvenience, potentially large argument lists), they should be used as much as reasonably possible. What is a Pure Function? According to Wikipedia, a Pure function has the following …

Read more

Guard Clauses – How to Clean up Conditionals

Guard Clauses - How to Clean up Conditionals

One of the first concepts new developers learn is the if/else statement. If/else statements are the most common way to execute conditional logic. However, complex and nested if/else statements can quickly become a cognitive burden and compromise the readability of a program. Guard Clauses Guard Clauses leverage the ability to return early from a function …

Read more

Optimize For Simplicity First

coffee simple

We can’t optimize for everything in software engineering, so we need to start with something, and that something should be simple code and simple architecture. For example, to over-optimize for speed in JavaScript, we might write our for-loops backwards to the detriment of readability. I believe we should optimize for simplicity first, and only make …

Read more