Good day, I’ll introduce my myself as Kurt Ma. Coll, currently a junior software engineer of Galleon.PH.
The FILM I shall be talking about is neither a piece of art that involves moving pictures nor a kind of a sheet or cover. It is an acronym that stands for Files, Intention, Logic and Language, and Machine. Whenever the team spots a bug, proposes some addition of a feature, or modification of a feature, I get to the topic and that will be my scope. Today, I shall give you an insight on how I analyze other people’s source code or even the source code of my past self.
The Files
I assume that when you read other’s source code, you start with one file. You start to read the file block-by-block. You are well aware of the language, and figuring out the logic. Does the code stand alone? Is it just a sheet? A leaflet? A booklet? A book? A tome? A library? As much as possible, be mindful of how many files in the system are participating in runtime, it’s what we call stack tracing. What are the files directly involved? Which brings us to…
Scope
This is a no-brainer. The scope determines if your refactoring is an overkill. Again, the scope of the code you read must accord to the scope of the contributor’s intent. The scope of your changes must also accord with the scope of your original intent. When you plan to refactor, you must make the scope of your intent appropriate to the scope of the issue.
Includes, Require, Import, Use
Depending on the language, there’s always that one language construct or library function that points to a file using a pathname, a namespace, or a class name. Always look for that. Also, be wary of libraries that use magic methods, it can impede your stack or file tracing if the library is not that documented.
What files are supposed to be directly involved? Speaking of “suppose”…
The Intention
The most important part we have. When looking into a particular function, you ask yourself: “What is the intention of the developer when the code was written?” As much as possible, the intention is clear, concise, and precise. This is where you see things go right or go awry.
Intention of the Writer
Let’s start with a simple objective. The programmer just wants to fetch from a user table and display it in a browser.
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
$sth->execute();
/* Fetch all of the remaining rows in the result set */
print("Fetch all of the remaining rows in the result set:\n");
$result = $sth->fetchAll();
print_r($result);
?>
// source: http://php.net/manual/en/pdostatement.fetchall.php
It basically just fetches data from a database, the intention is just to fetch a list of fruits. However, some things might go awry. However, the code shall not work if:
- the database of the fruit table is absent
- the fruit table itself is absent
- the logged in user of the database has no permission for the action
- something is amiss on the database engine
- Some random time-travelling witch from Zimbabwe cast a spell on your machine for no apparent reason.
And it cannot be solved by merely changing the snippet; you have to deal with the problems stated above by tinkering with your database settings or contents or countering that spell with an amulet or something. When an error arises due to a dependence of some outside influence or when you have written an implementation by mistake, it is called a side effect.
Side Effects
Side effects exist when some things from the environment are added to the mix. When doing System.out.println("Hello World"); in Java, the developer’s intention is to just print “Hello World”. However, some problems might arise in the terminal which is out of the intention. The functional call I mentioned uses either /dev/stdout of Unix or CON of DOS, which are system files. Side effects can be a “bug” or a “feature”, like a Glutathione pill that is supposed to enhance the health of your liver but whitens your skin. Or that Cobra Effect in India. Side effects and environment go hand in hand; you cannot eliminate it, but you can mitigate or contain it.
Side effects happen when you use the following:
- Third-party libraries
- The involvement of DBMS
- System calls and files usage such as
print(Python),scanf(C ),System.out.print(Java), and the like. I also mean file writes here. - Any variables for function calls involved with the compiler, linker, interpreter environment. An example is PHP’s $_GET or PDO functions.
- Any function that uses or calls any of the above.
If something in the runtime of a code goes wrong, look where the side effects were induced. When you need to use one of the items mentioned above, study and try the effects. Remember that PHP snippet earlier? The side effect happens in $sth->execute();.
Getting to Know the Writer’s Intention
The first thing you do when you analyze the intention is to read the code. Some snippets of code are clearly written that you can derive the intended effect with a minimal comment.
When you shall read someone else’s source code, you shall have an idea or gist of intention first from either of the following:
- How a certain feature of a program is run from the end user’s view
- Or the logs generated when something’s in debugging mode.
- The API documentation, the end user’s manual, or any supplementary sources
- The source code itself if it is concisely made and well-commented enough
- Or the words of the authors and contributors themselves
When you fail to have a good look through the first four ways aforementioned, the last one of the list is the last resort. Ask the contributor through e-mail, chat, or in person. It is your last resort unless the person has free time, you are in a hurry, or you are on the same team. Healthy communication is always a must.
Now that you have confirmed the intention of the contributor, you must confirm if the source code gives the intended results which lead to…
The Logic and Language
I don’t want to dive in too much into epistemology, but Language and Logic go hand in hand. Is language dependent on logic? Is logic dependent on language? Well, that’s for another day. However, I can assure that the logic of a source code depends on how the programming language was used. The use of programming language is shaped on how the logic in one’s mind was made. You must assure that the logic of the code matches logic intended by the contributor.
How well do you form your sentences? How well do you group your statements into paragraphs? How well do you form your article? How well do you form your statements? How well do you form your functions? How well do you form your… AAAAAAAHHHHH! You get what I mean, master both your command of the language and your logical skill so you can read codes well. Always know the syntax of the language and the semantics of your intention.
The possible mechanics varies per language. C programmers might be well versed in low-level coding. Java programmers will think in objects and interfaces. PHP interpreter started as a templating engine so early projects have mostly HTML files (per page) with PHP snippets inside. The Japanese language has no future tense, unlike in English where you can say “I will write” while leaving the question “when” not answered specifically.
A source code itself has its own logic just as the contributor has his own intended logic. The two must match or at least the code logic must fulfil the requirements. Do they match?
There’s a room with two people. Assuming that there is a need to engineer a mechanical rice cooker that turns off by itself by a timer, how will a Victorian-era English baron argue with a ninja from Japan who can’t speak English?
(If you ask why these two are included in just one letter, it’s because they both start in L. Also, I repeat, they go hand in hand.)
The Machine
Your code logic must also deal with the machine that runs it.
On what machine does this run? On what OS does this run? Does the OS affect the way the code runs? Does it involve mobile phones? Does it run well on mobile phones? On PCs? On any embedded system? What are the system requirements? On what kind of machine must it run? On most cases, you skip this step unless the constitution of the Machine and the OS affects the intended functionality in a huge way, like how file permissions are affected or the view of the web page changes when you use a mobile phone.
When thinking of the machine, you must think of the environment. The environment depends on the machine. Also, mind the system requirements for the program to run. Always. The background always appears first when you write a novel or a short story.
Conclusion
I’m actually using this technique to analyze the source code of Galleon.PH and the related systems. It’s a gist of how I grasp the involved files whenever a bug is reported. I call it the FILM approach. How do you like my approach?
Thank you for your visit! Thank you for reading! Want to say something? Here’s my e-mail: [email protected]
Have a nice day!
[Abandon all sanity all ye who visit my FB profile: https://www.facebook.com/kurt.mariacoll]