Writing code that other developers understand

Photo by Emile Perron on Unsplash

When you began your programming journey, you probably wrote code just to practice your newly obtained set of skills or for your own little personal project. You write the code, it works, so you forget about it. When you look at that piece of code after a few months, you do not understand it. 😕 As our programming journey continue, we begin to understand that programming is not just about the technical skills but also is equally about inter-team communication.

This is why it is important that you write code that other programmers understand. Either be it for peer review or just understanding legacy system, programmers will always be visiting your code. And as a programmer, it is your responsibility that you maintain your code likewise. In this article, we are going to discuss five important tips that will definitely make this part of the process easier. Lets go. 🏃

[1] Name everything cleanly

Names are everywhere in our source code be it function, class, argument, variables, file names, and what not. In fact, names are what make code readable to a programmer. So writing good names should be your first step in maintaining an understandable code base.

• Use names that are simple, clear, meaningful and intent-revealing for everything. This means your variable, your methods, your classes and your file names. If your variable or method name does not help to understand at least what the method or class does, you may want to rename them.

// what difference is this method calculating?
// diffrence in minutes?
// difference in days?
//difference in milliseconds?
function getDifference(DateTime dt1, DateTime dt2) { ... }

//a better solution ??
function diffInDays(DateTime dt1, DateTime dt2) { ... }

• Use names that are searchable and pronounceable to other programmers because this makes communication in your team much easier. It would be a shame if for every new programmer that joins your team, you need to spend some time just describing what the variables mean.

// which names would you prefer ??
int vId;
int videoId; 

double vidMs;
double videoDurationInMilliseconds;

• Use consistent naming pattern. Meaning don’t use different words to describe the same context. Don’t write three different class names like AdminManager, StudentControllerand EmployeeProcessor for the same concept. Don’t name your methods in three different ways like: getAdmin(), fetchStudent() and retreiveEmployee() because this is super confusing for someone trying to understand your code.
• Use Solution Domain Names because using programming-related terms like algorithm names, design pattern names, and mathematical terms is helpful to other programmers. So just name your class StudentFacadeif it is a facade instead of naming it something else.

[2] Comment your source code properly

After names, comments are the thing that makes a code readable. So go ahead and comment your source code, whenever needed. BUT REMEMBER !! Comments should not make up for bad code.

Bad code comments be like

• Write informative comments which further expresses the intent behind your code.

//matches the yyyy-MM-dd format
String dateTimeRegex = ((?:19|20)\\d\\d)-(0?[1-9]|1[012])-([12][0-9]|3[01]|0?[1-9]);

• Use comments that may clarify the code a little better, if needed.

assertTrue(a.compareTo(a) == 0); //a == a
assertTrue(a.compareTo(b) != 0); //a != b
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(bb.compareTo(ba) == 1); //bb > ba

• Provide link to websites like stackoverflow, laracasts if the external reference provides more clarity to the code you provide.

/**
* ref : https://stackoverflow.com/questions/475074/regex-to-parse-or-validate-base64-data
**/  
function validBase64Image(base64Image: string): boolean 
{
    const regex = /^data:image\/(?:gif|png|jpeg|bmp|webp|svg\+xml)(?:;charset=utf-8)?;base64,(?:[A-Za-z0-9]|[+/])+={0,2}/;
    return base64Image && regex.test(base64Image);
}

[3] Indent your code for better readability

Yes !! An often overlooked part for code readability is indentation. A code that is indented properly is so easy on the eyes to scan through compared to code that is badly indented.

Read more about this on this great article I found.

https://firstclassthoughts.co.uk/Articles/Readability/OptimalIndentSizeForCodeReadability.html

[4] Keep it short and simple

You may have come across with different programming principles like : Keep it Simple, Stupid (KISS), Don’t Repeat Yourself (DRY), Single Responsibility Principle (SRP) and what not. What all the principles have in common is that you keep your methods, classes short and simple.

No programmer wants to go through your 200 lines of code method in order to understand how the method works. He/she would just give up. On the other hand, going through methods with 5–10 lines of code seems relatively easy.

Image from refactoring guru

[5] Using tests as documentation

Unit tests are the best documentation of your code if you think about it. They provide information on how your system should behave under each circumstance. While you write tests for any behavior, you are expressing what exactly are you expecting from your code, how it should behave and how it should not.

Even better than documentation? Yes, if you allow your tests to. See, tests are never out-of-date because they will always be verifying the latest behavior that is expected of the code. Compare this to the actual documentation that developers might forget to update so will be out-of-date. Actually, tests are the primary source of truth and might also be able to verify that the documentation is correct.

This is also why you should be writing tests for your code. Some programmers think of tests as just a bug finding tool but that is just a pleasant side effect of a test. Code that has been maintained properly with all the necessary tests will self act as a great documentation.

Conclusion

A readable and understandable system is equally important alongside system that works. Programming is about understanding the system requirements, translating the requirements to code and changing the code as the requirements of system change. As programming is a team job, you will continuously be reviewing your fellow programmers code and yours will be reviewed by someone else. You will be communicating a lot talking about code, code and code! Which is why it is important that you maintain your code likewise.