Romain Delamare's Blog

Writing Good Code Comments

2023-09-12T00:00:00Z

During my career I have received conflicting advices about code comments. I recall a tech lead telling me I should comment everything and another telling me I should never comment because that is a code smell. Of course both were wrong, and since I’m right, I will now explain how to properly comment your code.

Documentation comments and code comments

I make a distinction between documentation comments, written for an external tool (such as Javadoc or rustdoc), and code comments, written for developers reading the code.

Documentation comments target users of the code and describe how to use it. They are great. You should write them whenever they are desirable (such as when writing a library). This article will not cover this type of comments. They are highly dependent on the language, and most tools have great recommendations on how to write documentation. You should follow these guidelines.

Code comments serve another purpose: they target developers to help them understand the code. Making the code understandable by humans is one of the most important goals of a software engineer, and code comments is one way to achieve it. Let’s see why, when, and how to write them.

When should you write code comments?

Depending on who you ask, the answer is “always” or “never”. Since you ask me, I think you should write code comments whenever the code is not self-explanatory and you have no other means of improving it.

The debate about code comments and code smell comes from a confusion on cause and correlation. There is a correlation between complex code and comments, because complex code requires more explanations. Since simplicity is a desirable trait, that makes code comments undesirable. This is a fallacy because you could have a complex code without comments, which is probably the worst situation.

More importantly, some complexity is unavoidable: sometimes you must optimize the code, sometimes there is a bug you cannot fix (e.g., a bug in a dependency), sometimes you must ship and cannot write a time-consuming refactoring. All these reasons, whatever their merit, could prevent you from writing simple and self-documenting code.

You should try to find other ways to convey meaning and remove complexity, but if that is not achievable, do write code comments.

Why not use comments more liberally? Because comments make maintenance harder. When the code is updated, it is very easy to forget updating the corresponding comments. A code with a lot of comments will become more difficult to maintain, and when too many comments are obsolete the code will be more difficult to understand

Adding meaning with good names

A good way to avoid using comments is to properly name functions and variables. No need to be creative, do not try to be funny. Write boring names. Be explicit. Write very long names if required.

Do not write

// computes the horizontal offset
fn hoff(x: i32) -> i32 {
    // add header column width
    x + 32
}

Do write

const HEADER_COLUMN_WIDTH: i32 = 32;

fn compute_horizontal_offset(x: i32) -> i32 {
    x + HEADER_COLUMN_WIDTH
}

Adding meaning by extracting functions

A function is not only useful to reuse a piece of code, but also for naming what it does. Function names are usually better maintained than code comments.

Do not write

fn rename_user(id: Uuid, new_name: String) {
    // load user
    …

    user.name = new_name;

    // save user
    …
}

Do write

fn rename_user(id: Uuid, new_name: String) {
    let user = load_user(id);
    user.name = new_name;
    save_user(user)
}

fn load_user(id: Uuid) -> User { … }
fn save_user(user: User) { … }

Dos and don’ts

Here are some guidelines for writing good code comments.

Dos

Do keep it short and simple. Just like your code, good comments are easy to read and understand.
Do add context. If there is a non-obvious reason the commented piece of code needs clarification, you should explain it. The goal here is to prevent someone who does not see the whole picture from trying to “simplify” the code and accidentally add a regression.
Do give improvement guidelines. If you know a way to improve the code but did not have the time to do it, or if an improvement relies on future work (e.g., a bug fix or a refactoring), explain it. This way, someone reading the comment in the future will know if they can rewrite the code and remove the comment.

Don’ts

Don’t describe trivial instructions. Comments in production code should not try to teach people how a language or framework works. If you need to teach junior developers, find a more appropriate way to do it. Code comments need too much maintenance.
Don’t write joke comments. We’ve all read them, but I think they’re bad and you are not helping anyone by trying to look clever or funny.
Don’t shame other developers. Comments are not a proper way to vent your frustration, and it’s never appropriate to be mean to someone for the code they wrote. You do not always know the constraints and difficulty they faced.
Avoid referencing other sources. It’s fine to add a link to a Wikipedia page, but avoid bug numbers or link to a bug tracking tool. The code will probably outlive any external tool or personal blog.

I used to avoid comments at all cost. Now I write more comments, but still feel like I should first try to make comments unnecessary.

Fast Acceptance Tests with Rust and PostgreSQL

2023-01-18T00:00:00Z

I have recently started writing a lot of acceptance tests. As I work using a test-driven design approach, they specify behavior while unit tests specify specific implementations. Another advantage of acceptance tests is that their description can be written and read by domain experts without requiring technical skills.

An acceptance test describes a scenario that describes the initial state, what happens, and what is the expected behavior. This scenario is executed from an entry point of your application. So in a hexagonal architecture, an acceptance test exercises the adapters, for instance a command line or http adapter.

Structuring your tests

The rust documentation uses the term integration test for any test that can only access the public interface of your library or application. This definition of integration tests encompasses acceptance tests and might not be what you are used to, but I will stick to it to keep it simple.

The recommended test organization is to have unit tests residing with the code of your application (in submodules with the #[cfg(test)] attribute) and integration tests in the tests directory. For instance if you have a TODO list application, you project structure could look like this:

Project file structure

📁 todo
├─ 📁 src
│  ├─ 📄 main.rs
│  ├─ 📄 persistence.rs
│  └─ …
├─ 📁 tests
│  ├─ 📄 delete_todo.rs
│  └─ …
├─ 📄 Cargo.lock
└─ 📄 Cargo.toml

The src directory contains the application code along with unit tests. The tests directory contains the integration tests, with each file being a different compilation target. If you need multiple files for a test, you can create a module directory with a main.rs file and the other files.

You can also create integration tests in other directories by adding new integration test build targets in the Cargo configuration:

Cargo.toml

[[test]]
name = "acceptance-tests"
path = "acceptance-tests/acceptance_tests.rs"

This will create a new test target, that can have its own submodules. There are other options, and you can even disable the default test harness, but that out of scope for this article.

The integration tests depend on all the crates defined in dependencies and dev-dependencies in the Cargo.toml file, as well as the code of your application or library (you can import it by using its name, e.g., use todo::persistence::*). If you are testing an application, you cannot import code from src/main.rs, but you can move this code to a src/lib.rs file and import it both from the main file of your application and from the integration tests.

Writing acceptance tests

An acceptance test executes a scenario, typically described with a sentence like “given ‹initial state›, when ‹event›, then ‹expected result›”. The scenarios can be written by or in collaboration with domain experts, so that actual and expected features are tested.

To set up the initial state of a scenario, you will need to design your application with dependency injection, for instance to allow setting the current time for the test. If “dependency injection” gives you a bad “object-oriented bloated magical framework” taste in your mouth, do not worry, it can be a parameter. For instance, you can add a function that gives the current time as a parameter for your application initialization:

src/lib.rs

impl TodoApplication {
	fn new(get_time: Box<dyn Fn() -> OffsetDateTime>) -> Self {
		Self { … }
	}
}

For your application you can just use the system current time:

src/app.rs

fn main() {
	let app = TodoApplication::new(Box::new(OffsetDateTime::now_utc));
	…
}

In an acceptance test you can define a function that will give a fixed time:

tests/acceptance_test.rs

#[test]
fn test_creation() {
	// Given an empty application at 1PM on January 9, 2023
	let now = datetime!(2023-01-09 13:00 UTC);
	let app = TodoApplication::new(Box::new(move || now));
	…
}

Dealing with persistence

If your application persists data in a database (or some other way), you have two choices for your acceptance tests: mock your persistence interface or use an actual database. While the former may seem easier and leads to faster tests, I tend to prefer the latter to test my actual persistence layer. You could write the acceptance tests with mocks and test your persistence layer with dedicated integration tests, but in my experience this is more tedious as you are going to write some test cases multiple times.

Using an actual database for your acceptance tests can lead to performance issues. If you create a new database from scratch for each test, the execution time per test will be very long. If you re-use the same database for each test you cannot have concurrent executions and you need to be very careful to properly reset the database between each test.

After several iterations, I have come up with a solution that allows for fast concurrent acceptance test with an actual PostgreSQL database. First you need to create a test database with the common initial state for all your tests, then for each test:

Create a copy of the test database with a random name
execute the test with that copy of the test database
delete the database copy

The default Rust test harness does not provide common test utility functions, such as before_each or after_each. To remedy that I create an AcceptanceTest structure. The AcceptanceTest::new function will create the database for the test, then instantiate the applications and anything that is required to execute the test. The AcceptanceTest implements the Drop trait to execute the test cleanup methods at the end of the test.

For instance, for the TODO list application, the structure could look like this:

tests/acceptance_test.rs

struct AcceptanceTest {
	app: TodoApplication,
	db_name: String,
}

impl AcceptanceTest {
	fn new(get_time: Box<dyn Fn() -> OffsetDateTime) -> Self {
		let db_name = generate_random_name();
		// copy database
		…
		Self {
			app: TodoApplication::new(get_time),
			db_name,
		}
	}
}

impl Drop for AcceptanceTest {
	fn drop(&mut self) {
		// drop database
		…
	}
}

The AcceptanceTest::drop method will be called at the end of your test, even if it panics. You can also add helper methods on AcceptanceTest to simplify your tests.

Copying the test database

In PostgreSQL, you can copy a database by creating a new database with the test database as template:

create database new_db with template test_db;

With this strategy, I have decreased the execution time of my acceptance test to an average of 100ms, down from around 1s initially (on a laptop with an AMD Ryzen 7 4750U CPU and 32GB of RAM). This allows me to use a test-driven approach with acceptance tests, and to run all my tests frequently to avoid regressions.

2022: what I played and what I listened to

2023-01-01T00:00:00Z

So long 2022! That was a strange year from me, my first as a freelance. I managed OK, with a contract that lasted half the year and let me work on a personal project… that did not progress as fast as I would like.

But enough of talking about the boring stuff, let’s talk about what I enjoyed in 2022: music and games.

Best albums of 2022

In 2022, I listened to a lot of new stuff, I even managed to do a musical advent calendar composed only of albums released in 2022.

So here are my top three albums of 2022:

3. Take all you can by Freedom Hawk, stoner metal

This album is a huge love letter to 1970’s metal and I have listened to it on repeat for a whole week after stumbling upon it. I did not know Freedom Hawk, so the good news is there are five more albums for me to catch on.

2. Folium Limina by The Otholith, doom metal

This album has all you expect from doom metal and more: low tempo, heavy basses, and violin. Beautiful from start to end.

1. Unison Life by Brutus, post-hardcore

Brutus is a Belgian post-hardcore trio that has been one of my favorite band since I have discovered them a couple of years ago. Their third album, Unison Life, feels like a perfect mix between the rawness of their first album and the refinement of the second.

Honorable mentions

These are 2022 albums that I loved, in no particular order:

Here’s What You Could Have Won by Kid Kapichi, punk rock
Myriad by Gaupa. Psychedelic Doom/Stoner metal
Grey Everlasting by Deathwhite. Doom/Heavy metal
Innate Passage by Elder. Prog/Psychedelic rock
Close by Messa. Doom/stoner metal

Best video games of 2022

Like every year I played a lot of games in 2022, but unlike other years, I played a lot of games in the year of their release. Here is my top three for video games released in 2022.

3. Expeditions: Rome

I had never played any game of the series before, and this one took me by surprise. The tactical fights are really clever and like in X-Com you can customize your mercenaries to match your playstyle, but I did not expect the roleplaying aspect to be so good. I chose to play as a woman, and the writers went out of their way to acknowledge it and most characters react to it realistically, it’s not a cosmetic choice. The game has some defaults (technically aged, a bit long) but overall a huge recommendation from me.

2. Citizen Sleeper

Citizen Sleeper is a roleplaying game that presents itself as a boardgame. You throw dice that you then use to perform actions that will allow you to survive on a space station that is (at first) very hostile to you. The survival aspect gradually leaves more room to a lovely story, where your choices seem significant.

1. Elden Ring

Not an original choice, but an obvious one. As a huge fan of Dark Souls and Bloodborne I had a lot of hope for Elden Ring, and From Software did not disappoint. It’s not just “Dark Souls with an open world”, clearly more than the sum of its parts. I know I will play this game for years.

Honorable mentions

Immortality: Sam Barlow does it again
Powerwash Simulator: best podcast game of 2022
Last Call BBS: sad that Zachtronics closes, but it’s a beautiful adieu
Deathloop: yes it’s a 2021 game, but I played it on Xbox where it was released in 2022
Vampire Survivors: after more than 80 hours I am not bored and I still got the DLC to play
Dome Keeper: a mining game with the cutest pixels

Best boardgames of 2022

Okay, I must admit I have no idea, because I almost did not play any new release this year. I have just received “Gloomhaven: Jaws of the Lion”, but I have yet to play it.

I did however play a lot of “Heat: Pedal to the Metal”, and I love it. The simulation is lighter than in Formula D, but the race is as intense and the risk management is at least as good. Also, there is a clever and simple way to include more cars that race automatically, which makes it possible to play with few players (or even solo) and still have a full grid.

That’s it for 2022, let’s hope 2023 will be better for you or me.

2022 Music Advent Calendar

2022-12-01T00:00:00Z

Last year I did a music advent calendar for friends, and I’m doing it again this year. The rule is simple: each day a new album. This year I chose to only do albums released in 2022.

1. As Above, So Below by Dead Sun Rising

Doom/post-metal

2. Once Twice Melody by Beach House

Dream pop

3. Close by Messa

Doom/stoner metal

4. Lucifer on the Sofa by Spoon

Indie/blues rock

5. Innate Passage by Elder

Prog/psychedelic rock

6. Grey Everlasting by Deathwhite

Doom/heavy metal

7. Only the Strong Survive by Bruce Springsteen

Soul/R&B

8. Myriad by Gaupa

Doom/stoner metal

9. Once Bit Never Bored by Taipei Houston

Garage rock

10. Over Opiated in a Forest of Whispering Speakers by Seven Nines and Tens

Progressive metal

11. A Bit of Previous by Belle and Sebastian

Indie pop

12. Those Who Hunt at Night by Save Masters

Heavy metal

13. Here’s What You Could Have Won by Kid Kapichi

Punk rock

14. Gnosis by Russian Circles

Post-metal

15. New Low by Greet Death

Shoegaze

16. Leather Terror by Carpenter Brut

Synthwave/darksynth

17. The Car by Arctic Monkeys

Indie rock

18. Our Side of Their Story by Federale

Ennio Morricone core

19. DISCO4 :: PART II by HEALTH

Noise rock

20. Dreamkiller by Sumerlands

Heavy/power metal

21. Two Ribbons by Let’s Eat Grandma

Synth pop

22. Take All You Can by Freedom Hawk

Stoner metal

23. Folium Limina by The Otolith

Doom metal

24. Unison Life by Brutus

Post-hardcore

Fin

That’s all folks, I wish you all happy holidays!