software and stuff

Help me and others understand your code

It’s hard to make things work. But it’s even harder to explain how you did it. Here are a few things you could do to help me, you, and others understand your code.

Good formatting. Yes, that space between operators is important. Line lengths, line breaks, blank lines, camelCase, snake_case — they all make a difference. Be consistent, adhere to a guide.

Careless naming. Don’t use abbr. Don’t make me guess. Don’t mislead. Be precise. What is it? What does it do? Why it exists?

Conditionals and switch statements produce different outcomes. Which means I have to read the code again, and again, and again…

Nested loops, nested loops with conditionals 😮 . Same as above, only a million times worse. Get rid of them.

Hide stuff I don’t need to know. I don’t need the details. I want to be able to say “ah, it does this” without knowing exactly how. Write in cascade. Start with high-level concepts and add more details as you go downstream.

Make smaller things. It increases the number of files, classes, and methods and makes it harder to reason about the whole system. But that’s the idea. I don’t want to reason about the whole system. I can’t. Nobody can. I’m more efficient reasoning about small things. One at a time.

Don’t fall into the “I’m the only one working on this” trap. There are at least two people working on a project during its lifetime. The first one is you. The second is the you after a few months.

Put some more care into your code. Name stuff a little better, split classes and methods into smaller ones, make it look and read well.

It's not your code. It's our code.