THE ART OF READING CODE (as a newbie)

— THE PART THEY LEFT OUT IN COLLEGE

When you’re in college, you learn programming from a basic/fundamental level. You learn about simple data types (variables, lists, tuples, structs), syntax, compiling and which language is good for what purpose.

This introductory journey isn’t just a preamble; it’s a pivotal phase in your learning path. You in turn use this knowledge to build projects such as a simple calculator, to-do app or a recipe app further deepening those fundamental concepts. Most of this small projects contain less than 100 lines of code. However, as the journey unfolds and the terrain shifts, a stark reality emerges: the real-world projects, vast and sprawling, comprise thousands, if not millions, of lines of code. Even with a well written documentation, it can sometimes be challenging to figure things out when you get started on such projects.

Amidst this complexity, a fundamental skill emerges as paramount: the art of reading code. Not just reading code, it’s about unraveling the logic and discerning the underlying architecture. This ability to decipher code isn’t just a skill; it’s an indispensable asset.

From John Willes article, our product as software engineers, is not just the code we write, but the ‘thought process’ that goes into the code. When we read somebody else’s code, we’re not just deciphering strings of characters; we’re delving into the intricate web of thought patterns that birthed those lines. Zaki Rullin refers to this as Cognitive Load, more on that here.

In the act of coding, we find ourselves at a crossroads, torn between the imperative of articulating our thought process explicitly within the code and the pursuit of cleanliness and efficiency. Often, the former entails a meticulous unraveling of ideas, a deliberate exposition of intent, which, while invaluable for comprehension, it might go against the principles of writing clean code.

When you get a new job and get thrown into a code base with 100K+ lines of code, interpreting the code into the thought process that went into writing that code is the first thing you’re required to do. This can start with understanding the software architecture and design patters of the specific tools or frameworks used.

In the remaining sections of this article, we will look at a few lines of code and discuss on what tips and tricks can be deployed to achieve the above mentioned objectives.

Let’s take a look at the piece of code below;

import hl7
def create_hl7_message(test_request):
    patient = test_request.patient
    hl7_message = (
        "MSH|^~\&|Sender|Receiver|HL7APP|TEST|20240101000000||ORU^R01|MSG00001|P|2.4\r"
        "PID|||{patient_id}||{patient_name}||{date_of_birth}|{gender}\r"
        "OBR|1|||{test_id}||||||||||||||||"
    ).format(
        patient_id=patient.id,
        patient_name=patient.first_name + " " + patient.second_name,
        date_of_birth=patient.date_of_birth.strftime("%Y%m%d") if patient.date_of_birth else "",
        gender=patient.gender,
        test_id=test_request.id,
    )
    return hl7_message

Now, now, don’t get scared, this is a simple Python function that takes a test request object and returns a hl7_message string. Let’s break it down. The skeleton of the function looks like this:

def create_hl7_message(test_request):
  patient = test_request.patient
  hl7_message=().format()
  return hl7_message

NB: HL7 is a data standard used in healthcare most commonly in medical records systems or interfaces.

We also need to find out what happens inside the function. If we break it up, we get two variables. One, extracts the patient object from the test_request patient = test_request.patient, the second hl7_message=().format() takes some data and formats it. In simple terms, the second variable takes a predefined format of data then gets specific data from the patient objects and formats it according to the per-defined format.

patient = test_request.patient
hl7_message=().format()

What would one need to understand this code?

1. The syntax of the specific language it was written in — i.e how do we define, functions, variables.
2. What problem is the code is supposed to solve — take patient data and convert to hl7 format.
3. What standard libraries are we using — in above code, none.
4. What third part libraries items are we using — hl7, how do you know this? Checkout any import statements.

This does not always work in the order I’ve listed them above. You might start by identifying the libraries, then syntax then the problem in some projects then reverse the steps in another.

An important step in understanding the syntax is identifying the reserved keywords for that specific language and the user defined keywords. Reserved keywords are note supposed to be used as variable names, function names, or any other identifiers in your code. If you’re working with Python items such us def,return,False, while, with,are reserved...