Let’s Take Out the Trash: Writing Cleaner Code

Clean code plays a major role in the understandability of a code, along with that so does its readability, changeability, extensibility and maintainability. There are numerous examples of poor code taking organizations down or reducing a decent product into a disaster. Clean code is vital for building a successful maintainable product, especially when you are part of a developer team. You should always think about the next person who will maintain your code.

First thing first, always follow the standard conventions agreed by the team. The team should be speaking the same language, each member should be able to work with code written by any other member of the team. Next is to keep the code as simple as possible, pretend the person maintaining your code is stupid if you must. Reduce complexity wherever possible.

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

— Martin Fowler

Some Tips and Examples

• Consistency is key. If you do anything one way, be sure you do everything else the same way.

Bad

$room-number; // kebab-case is used
$roomName;    // camelCase is used

Good

$course-name;
$course-teacher;

• Variable names should speak for themselves.

Bad

$x; //stores user id
$y; //stores course id
$z; // stores user’s role in course

Good

$userId;
$courseId;
$userRoleInCourse;

• Boundary conditions should be encapsulated, all their processing should be put in one location as they are hard to keep track of.

Bad

if (studentId + 1 < numberOfStudents) {...}

Good

nextStudent = studentId + 1;
if (nextStudent < numberOfStudents) {...}

• Dedicated value objects are preferred over primitive types.

Bad

var_dump(“false” == false)

Good

var_dump((bool) “false”)

• Reduce logical dependencies, do not write methods that rely on something else in the same class to perform successfully.

Bad

$tag; //default is null
method setTag(tagValue) {…}
method compareTags(otherTag) {…}

Good

method compareTags(tag, otherTag) {…}

• Avoid negative conditionals.

Bad

if !(a > b) {…}

Good

If (a <= b) {…}

• When a line of code is no longer needed, do not comment it out, simply remove it.

Clean Code in Badaso LMS

In the development of Badaso LMS, our development team use two tools for maintaining code quality: StyleCI and SonarQube. StyleCI is a continuous integration tool that enforces your code style preferences automatically. What made it convenient to have is that not only does it point out code smellss, it also show you how to fix them.

On the other hand, StyleCI is not perfect, and some code smells may pass the check. With that in mind, even when a branch’s pipeline is already green (passed StyleCI and SonarQube) a code review should be done and only when a feature branch has at least 2 approvals from members who are not the author of the code can that branch be merged into staging.

By that commit, I have passed both StyleCI code smell check and SonarQube coverage check. However, I was soon enlightened on how tools will never beat a human being.

Apparently, this is why code review is important. Without it I would have merged a branch that had still contained code smells. I am truly grateful that I have been blessed by team members who truly care about the quality of the code, not just having it look good in the report. This sprint taught me a lot and I am excited to learn more.

“Are we debugging in a panic, poring over code that we thought worked? Are customers leaving in droves and managers breathing down our necks? How can we make sure we wind up behind the right door when the going gets tough? The answer is craftsmanship.”

— Robert C. Martin

References

Martin, Robert C. Clean Code: A Handbook of Agile Software Craftsmanship. Upper Saddle River, NJ: Prentice Hall, 2009. Summarized by wojteklu in https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29

Butterfly. (2021, December 8). Clean, high quality code: A guide on how to become a better programmer. Butterfly. Retrieved March 22, 2022, from https://www.butterfly.com.au/think-pieces/clean-high-quality-code-a-guide-on-how-to-become-a-better-programmer/

Gefroh, J. (2018, September 8). Why consistency is one of the top indicators of good code. Medium. Retrieved March 22, 2022, from https://jgefroh.medium.com/why-consistency-is-one-of-the-top-indicators-of-good-code-352ba5d62020

mohabdelaziz95, M. A. E. (n.d.). Value objects — your savior from primitive obsession. github. Retrieved March 22, 2022, from https://mohabdelaziz95.github.io/blog/2021/value-objects

Luke illustration was taken then edited from luke.exe (timestamp: 5.19) https://www.youtube.com/watch?v=4s1KVaZ5bUE&ab_channel=RedPopsicle. Image can be found in https://ristek.link/luke-exe