What I learnt after 15 years of Software Engineering. Part 1
In these articles I’m collecting — in a very concise form — what I’ve learnt in my 15 yrs as a software engineer in more than 12 different companies, middle and large projects, small and large teams, but also in more than one single-handed project.
Technical debt is not your friend
Deliberate technical debt is a loan, and it get worse with time. Always leave the code in better state than you found it (boy scout rule); if something is too big or unrelated for a refactor in your current branch, create a ticket and flag it up in order to be acted soon. The more you wait the more it’ll get worse and overall you’ll have spent more time changing code written on top of those components that should have already refactored. That doesn’t mean you have to refactor every single time, things evolve and change often too quick, but consider cleanups and refactor on a weekly or monthly basis.
Simplify code and naming as much as possible
After you have written your test and your code works, spend time renaming (use IDE inline/extract methods and other refactor utilities) with naming that allows the code to be read clearly. Use an IDE (like IntelliJ) that allows to do that safely. Simplify as much as possible, and — when possible — remove the functionalities not strictly necessary that complicate the logic too much . Naming is one of the most difficult to get right, and if not done properly it means time consuming when looked at later (and that includes you).
Look at this code, what it does is crystal clear:
if (user.canView(paper)) {…}But this equivalent code takes more time to understand what it does
if (usersById.get(user.getId()).containsKey(paper.getId())) {...}Beauty of style and harmony and grace and good rhythm depend on simplicity — Plato
Personal preferences (code style, monolith vs microservice, serverless vs k8s …) are not a reason to refactor
I’ve noticed this a lot in my early career years with young developers. Fighting for code style is a waste of time, it doesn’t really make a difference in the end. The team should adopt a code style that is aligned with the rest of the libraries, and minimise conflicts, or have a real advantages, any other preference is a waste of time. Refactoring the code for personal preferences is even worse, especially when the project already started. Changing the code introduces a risk (even if tests are written), and alters all the version control owner annotations making it more difficult to find the developer whom originally wrote the code starting from the business spec. Personal preferences are not a reason to refactor, nor is changing existing working code to match your style.
For the same reason, adopting a new tech or architecture just because it’s trendy or cool or on a hype could be a serious harm for the project to succeed, I’ve seen more than a project failing because of that. Any architectural choice has to be a result of a cost-benefit analysis. I’ve noticed a recent preference to use microservices, often serverless, although not really adding value to the project and in some occasions obliging to a complete rewrite later on as unmaintainable. If you are curious about a tech stack, experiment on your projects, not on a business that invest serious money on it, it’s your responsibility to choose the best tool the market offers and also go against everyone that follows his/her preferences. When I wanted to play with serverless and dynamoDB I’ve created a project with it, and when I realised I’ve learnt enough and the project was evolving in a different way than expected, I‘ve switch over to a main big servie with Quarkus and Hibernate frameworks, which turned out to be the best choice and made me better understand pros and cons of serverless architectures.
“…history has shown that large enterprise systems can be built from monoliths and component-based systems as well as service-based systems. Thus services are not the only option for building scalable systems.” — Robert Martin — Clean architecture
Always start from the official documentation and contribute to the community
Any time you work on something, always start with the official updated documentation of the libraries and framework you use. After that you’ll have guidelines on what the library is capable at the current version and you can now google how the community solved the problem, and be able to exclude solution done with old library/framework versions. It’s likely somebody already solved your task so you can save time. If you manage to solve it better, then comment or respond to their article, it takes minutes and it also helps you, it’s likely one day you’ll have to reimplement that task and you’ll find again your solution (with maybe comments added to it for further improvements). You are not wasting time nor cheating doing this, software engineering is more about learning, sharing, teaching, adapting solutions, wiring and switching libraries than coding.
More to come
