The 5 Mistakes Programmers Still Make in 2021

Mistake 1: no documentation

The top mistake from all projects: no documentation whatsoever.

Without documentation, how do you even get started? How can you learn the project structure, the software architecture, and where to find the exact files you want to modify, update or just read?

Documentation is the key to a successful project, open-source or not. Make sure you document at least how to use the project, how to test and deploy it.

Want to really go fancy? There are some good projects to help you write documentation, such as docusaurus.

Mistake 2: no comment

Even if you have documentation, you still need to understand the code. Even if you code for yourself, you will still likely not remember what a particular piece of code is doing or how it uses. Of course, you do not need to write a comment for the function int addToNumbers(int v1, int v2) but you will probably need to add some for the function computeQuotaForUser(int userId) (especially if the quota depends on multiple inputs).

Always comment either when the code is not obvious or used at multiple critical code paths.

Mistake 3: unreadable code

Have you ever taken multiple hours to read a piece of code and understand what it does (especially when there is no comment — see mistake 2)! Every developer had such a moment when they do not understand what the code they read is doing.

Make sure your code is readable, no only by having comments on non-obvious code but also by

• adopting consistent style across the codebase
• naming variables with what they are supposed to do and how they are quantified (for example, prefer timeRemainingSeconds rather than timeRemaining — the latter does not specify the unit)
• write small, readable units of code that can fit on a screen (e.g., 40 lines of code)

Mistake 4: no test

Another top mistake is never to have any unit or integration test. Sure, you tested your code manually and ensured it worked on your machine. But there is no guarantee that you or your colleague will run the same tests and that the code will run in a clean environment (such as a CI/CD pipeline).

To guarantee your code is still operating as expected, write unit tests and run them at every change in your CI/CD pipeline.

Mistake 5: do not use strong typing when available

Many languages used today (e.g., JavaScript or Python) do not use strong typing. Fortunately, they address these problems by introducing typing (either as part of an extra layer — as with TypeScript, or as part of an optional module — as with Python).

Strong typing avoids shooting yourself in the foot and ensures that you do not add apples and oranges. Even today, some developers are still adding strings and integers, expecting that "1" + 1 will equal to 2 (spoiler alert, it is equal to 11).

Such issues are often hard to find, and finding the culprit is like looking for a needle in a haystack. To avoid such issues, use strong typing when available and always declare your types.