Teachings of a Samurai Engineer

Teachings of a Samurai Engineer 1: Greetings and a Declaration on Programming Stance

I’m Michiaki Furusho. I often use the handle “gallu” on the Web.

I’m Michiaki Furusho. I often use the handle “gallu” on the Web.

I have just under 40 years of programming experience (my first programming language was N88-BASIC). I have been working professionally as a software engineer for almost 25 years now.

I often create Web applications. From C I learned C++, and then Perl, and through those languages, PHP. I began with PHP3, and have been using PHP as the mainstay for my work since around the time of PHP4. So you can say that PHP has been my principal language for more than 15 years.

I still program with PHP today. I also take on a relatively varied range of work, such as design (including of databases, infrastructure, and operation plans), operations, code refactoring, project management, and teaching at technical colleges.

The types of jobs I’ve been involved in have also been quite diverse, including BtoC systems, BtoB systems, in-house systems, and videogames.

Being an engineer for this long in such a manner, and being involved in education, I’ve come to realize quite a few things that I wasn’t aware of in the past. I’d like to share some of my musings with you.

When writing about these matters, I should start by first discussing the “stance that forms my foundation.”

Bjarne Stroustrup wrote a paper called “Learning Standard C++ as a New Language.” In it, he writes a sentence that appears in both “1 Introduction” and “5 Summary.” I often quote this sentence at the start of courses I teach. So I’d like to quote it here:

“We want our programs to be easy to write, correct, maintainable, and acceptably efficient.”

This short sentence is full of important implications.

First, it is extremely important to be “correct.”

For example, in an accounting system, if an error occurs occasionally when calculating the total, this situation is “not correct” and greatly undesired. When using the integer type in PHP, if PHP_INT_MAX is used in an execution environment (32-bit) where it is 2147483647 (approximately 2 billion), and a company’s accounting system has a monthly or yearly total that reaches 3 billion, if that system is unthinkingly implemented, then that total is interpreted as a float instead of an integer. This is PHP’s specification when a value exceeds the range of the integer type. As a result, an error occurs because of the precision of the floating-point number, depending on the value. The number may be slightly off. Making sure that such a phenomenon does not happen is critical.

If you grapple with code as your job instead of a hobby or lesson, then making sure that your code is “maintainable” is also an important element. This is because the times change, businesses evolve, and new needs arise.

Speaking in terms of extremes, there are two kinds of difficulties in maintaining code: “difficult code” and “dirty code” (e.g. spaghetti code). The former kind requires the maintainer to have a high level of skill and knowledge. The latter kind can be prevented, avoided, and fixed.

There are several methods and approaches to preventing dirty code. These include “DRY code (design)” and “conscientious and appropriate commenting.” When writing such code, advanced knowledge of PHP to a certain degree is helpful.

As a rule, it is hard to say what makes a program “easy to write,” as there are considerable differences in individual subjectivity, points of views, and experiences. Still, because mistakes easily occur when code is not written cleanly and clearly, it is necessary to pursue this goal to a reasonable extent.

A set of coding conventions prepared by a team is useful, as is a tool such as PHP Coding Standards Fixer. Writing code concisely because you know a way of writing code is also considerably helpful. So it is often important to understand such a coding style and be able to use it.

It is extremely difficult to achieve a balance of writing clean code and writing code that is “acceptably efficient.”
If you write code that prioritizes efficiency, it may become difficult-to-maintain code. On the other hand, if you don’t consider efficiency at all, your code will become extremely heavy and consume a lot of memory. You must seek the appropriate degree of efficiency in the required environment.

For example, in the context of building a Web system with PHP, writing difficult-to-understand, difficult-to-maintain code to achieve a difference of 10 milliseconds is most likely unacceptable, although it depends on the onsite situation.

To consider balance while trying to achieve appropriately light code, you must have suitable knowledge, including of design.

So the short sentence I quoted is full of critical implications.

Besides this, I think the two principles of DRY and YAGNI are very important.

DRY: Don’t Repeat Yourself

In a nutshell, “Don’t repeat / don’t duplicate.”

This seems natural at first glance. But when you create a system, it is surprising how often phenomena such as “This section is a copy” and “This description is written in locations A, B, and C” (indicating copy-and-paste jobs), and “I wanted to consolidate code in one location but I duplicated it and commented on it instead because I couldn’t do it” appear.
If you have knowledge of PHP and the design method and coding style based on this knowledge, you can often avoid these problems.

YAGNI: You Ain’t Gonna Need It

In a nutshell, “This isn’t used, right?”

Implement what you need when you need it. This can be called commonalization (functionalization, methodization), but if you expand implementation, thinking “I may use x,” then there is no end in sight.
Implement what you need when you need it. Create a clean design and code accordingly so that you implement something when it is needed.

Personally, I call this “gap/gapless design.” If you can write code in this style, then you can implement YAGNI without fear.

There is also the principle KISS (“keep it simple, stupid”). I also like this principle and value it.

Although it is a simple way of saying “A foundation does not dictate the first steps,” there are various debates about KISS, such as “Keeping it simple is surprisingly difficult” and “What makes code simple?” So I often first teach DRY and YAGNI.

The above describes my stance to coding.

Going forward, I’d like to write contents for beginners, on topics such as “PHP knowledge,” “design using PHP,” and “different coding styles for different situations,” as well as contents for those taking a further step beyond.

Part 2

Part 3

Part 4

Part 5

Part 6

Part 7

Part 8

Michiaki Furusho