MILF Analysis

Good day! I’ll introduce myself as a Software Engineer who aspires to be a Software Architect.
Before you start writing an understandable English text, you must have read an English text before, or you’ll have nothing to imitate. You’ll always need example. When reading a source code, I have an acronym in mind: MILF. It’s like a guideline to know what to check first.

The MILF I shall be talking about is neither a group of Philippine Islamic separatists nor a kind of a performer with a beautiful maternal aesthetics. It is an acronym that stands for Machine, Intention, Logic and Language, and Files. Whenever someone spots a bug, proposes some addition of 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 Machine

Will this be run on a desktop or laptop? On a smartphone? On an embedded device? On a virtual machine (an imaginary computer inside a real computer)? 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. Also take note whether the file is a system file or an application.

When thinking of the machine, you must think of the environment. The environment depends on the machine. Always. The background always appear first when you write a novel or a short story.

On what machine this is supposed to work well? 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 Uganda cast a spell on your machine for no apparent reason other than amusement.

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 by offering a yellow rat, or something. When an error arises due to 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 in the environment are added into 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 it also whitens your skin. Or when the rugby manufacturers use toluene to enhance the adhesiveness of rugby but was abused by some street rascals for a heavenly experience because the manufacturers were not aware on the effects of toluene (or chose to ignore it because it’s a “feature”). Side effects and environment go hand in hand; you cannot eliminate it, but you can mitigate or contain it. Functional Programming afficionados would like to avoid or contain side-effects: they have monads or something.

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.
• 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 on 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 in the same team. Healthy communication is always a must. Free coffee or beer please.

Now that you have confirmed the intention of the contributor, you must confirm if the source code gives the intended results which leads 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 programming. Most PHP programmers of 2005 just create sophisticated HTML templates. Java programmers will think in objects and interfaces. 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 fulfill 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 shinobi from Japan who can’t speak English?

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 stands alone? It it just a sheet? A leaflet? A booklet? A book? A tome? A library? As much as possible, be mindful on 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 when you plan to refactor, you must make the scope of your intent appriopriate to the scope of the issue.

Includes, Require, Import, Use

Depending on the language, there’s always that one langauge 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 uses magic methods, it can impede your stack or file tracing if the library is not that documented.

Conclusion

I’m actually using this technique to analyze the source code of many libraries and the related systems. It’s a gist on how I grasp the involved files whenever a bug is reported. I call it the MILF analysis. How do you like my approach?

This is my original approach. I also have another approach. Here’s the other one