How to code better?

Sysadmins are traditionally more operators than developers, they code mainly scripts for automation reasons (shell scripts, Ansible, Terraform, aso). In addition, they can find themselves in situations where they need to analyse code or even decompile programs. Some sysadmins lack good programming methodology, that was my motivation to dig deeper into this subject.

Are there simple rules to follow?

As a general rule, we can say that either somebody else is using and/or changing your code. Seldom it’s the same only person that writes, modifies and uses code. As you interact with persons, communication and soft skills are key to success.

There is an inspiring art piece “How to work better” by artists Fischli/Weiss painted at a wall at Binzmühlestrasse 14 in Zurich:

Photo credit: zurich.com

The ten rules are:

How to work better?

1. Do one thing at a time
2. Know the problem
3. Learn to listen
4. Learn to ask questions
5. Distinguish sense from nonsense
6. Accept change as inevitable
7. Admit mistakes
8. Say it simple
9. Be calm
10. Smile

I asked myself if there could be fundamental, easy rules on “How to code better”. Here’s my essay:

How to code better?

1. Trust yourself and others
2. Understand objective(s)
3. Don’t assume, ask users
4. Work together, not alone
5. Understand problem/Fix root cause
6. Don’t repeat yourself
7. Work on things that are easy to change
8. Respect limits (cultural, technical, your own)
9. Reduce complexity as much as possible
10. Create minimal viable products
11. Test, whenever possible automatically

Theory

Plenty of theory can be found online by searching for “clear code” or “programming style”. In addition, there is a great book “The pragmatic programmer” by David Thomas and Andrew Hunt. It contains practical and easy to understand examples. I would like to focus on two fundamental principles:

Easier to change principle

A thing is well designed when it adapts to the people using it. For code, this means adapting through change. At the end of a programming session, you should ask yourself: “Did what I just coded make the overall system easier or harder to change?” You can almost be sure that every single line of code in your first version will be modified during the lifetime of your code.

Some real worlds examples:

• If you need to choose between variants, you should decide for the ones that are easier to change in future.
• Regardings requirements, it’s easier to isolate them as it makes your solution easier to change.
• Huge problems should be divided into smaller ones that are easier to handle and solve and also easier to change.
• Accurate naming standards makes it easier to read code and change it.

A simplified software lifecycle may look like this:

After an initial release, there are some updates, and finally a software will be decommissioned. What is important that efforts to end initial release are relatively small compared to the ones for update and decommissioning. If things are easier to change right from the beginning, it helps bring down efforts to the subsequent phases.

Don’t repeat yourself principle

Every piece of knowledge should only has one representation in your code. Your code is easier to change as you only need to change one representation.

Some real worlds examples:

• In programming, use functions, modules, libraries, classes
• In data modelling on relational databases, use normalisation and avoid redundant data. There are exceptions when it comes to tuning: as you typically use the 3rd normal form, some models could deliver better performance when using 2nd normal form instead.

Interviews

Besides theory I wanted to know whats true and false in the real world. For that reason I interviewed a bunch of people to get to know their experiences.

One have to say there is no general and clear answer to all problem. What works for one person/company may not work for another. It’s a good thing to stay open, test new methods, to make failures and learn from it.

Here is the interview summary:

Q1: What techniques do you use to make your code a success?

Peer programming and code review are both suitable to introduce new employees and if one deals with critical code passages.

Before starting coding, it’s critical to understand key objectives, requirements, use-cases and concepts. On the other hand, one need to be able to live with uncertainties.

When it comes to documentation, comments in code are not sufficient. A picture says more than 1000 words and cannot be put in code. Don’t forget to document why you did like this.

It’s import to test code and use precise test cases. Whenever possible test together with end user or at least simulate users. If it’s practicable, follow test driven development methods.

Ensure that your code is traceable. Issues happen and if they are not repeatable, there is no problem to solve. Log levels should be increasable without restaring or a service interruption. Include input and output variables in logfiles.

Q2: What mistakes should you avoid at all costs? 

• You should not directly start coding.
• Do not use hardcoding, always use variables and validate their values before using them.
• Avoid unformatted code as it’s very hard to read and understand.
• Avoid one man shows.
• Too little communication with customers or within team can lead to misunderstandings and wrong assumptions. It could be a huge effort to change code that is not following objectives and requirements.
• Do not write concepts that are several hundert pages. No one will ever read or understand it. Check if theory works in real world from time to time and adopt.
• Do not always jump on the latest trends. Not everything that is new is always better. Sometimes it is better to fall back on the tried and tested.

Comments wanted

What is your experience? What works for you, what does not? Thanks for commenting.