Forem: Igor Fil

Infrastructure As Code Is Wrong

Igor Fil — Wed, 12 May 2021 21:11:11 +0000

There are several problems in computer science that are very hard. One of them is naming things. So it should no surprise when names make little sense.

One of the "bad" names is "Infrastructure as Code". I think it misleads more than it reflects the idea.

In the era of self-hosted systems, infrastructure was managed by directly handling hardware and manually setting configurations. This approach does not work any longer in the age of cloud computing. It does not scale, it is too slow, and too risky.

Instead, the "Infrastructure as Code" (IaC) represents a different idea - to represent infrastructure and configurations as machine- and human- readable text and then use automation to manage it. These tools can create infrastructure components as many times as we like, do it very fast, and make sure they all are exactly the same.

If we take for example Terraform, provisioning of EC2 instance will look something like this:

resource "aws_instance" "web" {
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  tags = {
    Name = "HelloWorld"
  }
}

It is human-readable (and writable), but it can also be processed by automation. Terraform will do all actual calls to AWS to provision the instance for us based on configurations in text files that we give it. Also, these files can be version-controlled. We can put them in git and track changes to infrastructure.

Just like code, right? But is it really code? It surely looks like it, but does not feel like it to me. What is code? Code is logic. It is either a series of imperative commands,

if this do that, else do the other thing

(C++, Java, Python, etc), or declarative computation pipelines

take data, pipe it through this function and apply this function to result

(Haskell, Elixir, Clojure, etc).
But in case of IaC, we describe the desired state of infrastructure

I want 2 EC2 instances with such and such properties

We don't specify how exactly to get them. We don't specify what APIs to call and in what order, we don't specify logic to handle dependencies between resources. Instead, we rely on Terraform (or CloudFormation) to figure that out and do it for us.

The actual logic, the code, is the tool, Terraform or CloudFormation. What we give it, that textual description of what we want, is rather data.

I have seen people take the name "Infrastructure as Code" for the face value and treat it the same way as the actual code. They try to fit loops, conditional statements and other imperative constructs into it, as if it was Java or C#. And it usually ends up pretty badly.

We should be very clear about what IaC is all about. Terraform or CloudFormation are not programming languages, not even frameworks. IaC is about being able to declaratively say what infrastructure you need and then use tools that will figure out how to get it for you. Trying to fit extensive logic into it is like trying to dig the ground with an iPhone. It can do it to some extent, but it is not what it's all about.

Infrastructure as Code seems like a very misleading term to me. When using this approach, you don't write actual code (logic) that will create infrastructure. You create configuration files that contain data that says what the infrastructure should look like. You create data, not code. That's why in my mind, "Infrastructure as Code" is actually Infrastructure as Data.

How To Measure Productivity?

Igor Fil — Sat, 30 Jan 2021 00:03:21 +0000

How do you know that you are productive? What makes a productive day for you? If you have people reporting to you, how can you tell if they are productive or not? I have heard these questions many times and I have heard just as many answers.

Can you measure?

Measuring productivity is hard. This is not a precise science. There are no common units, rules, or measurements. But if I wanted to say that today I was more productive than yesterday, how can I turn it from something subjective (“just felt productive”) to something comparable, apples to apples? I would need to measure my productivity somehow. But how can I quantify my productivity? How can I transform it from abstract word ‘productivity’ into something that I can count?

Measure output

The naive method is just to measure output. If I have a machine producing lollipops, I can just calculate how many lollipops it can produce in a day. The more lollipops - the more productive the machine is. Maybe it is possible to quantify a person’s productivity the same way? If I am a programmer - I produce source code, right? The more lines of code I produced - the more productive I am? Not so fast. It is important to understand what exactly do I measure. If I only want to produce piles of source code - maybe it is better to just use some code generators? They can produce thousand lines of code per second. But code alone is not what I do and get paid for, right? Counting amount of code is a fundamentally flawed logic. Code by itself is not worth anything, it only exists to solve some particular problem. We cannot say that the more lines of code - the better the solution is (I would rather advocate for the opposite).

Measure progress

It turns out that I cannot use code to measure productivity, maybe I can measure productivity by looking at my progress towards goals? Usually I break down distant goals into smaller milestones and tasks. What if I could count the number of tasks that I completed per day and use that as a measure of productivity? That sounds intuitive and pretty reasonable. But the problem is, not all tasks are made equal. ‘Fix failing unit test’ task is greatly different from ‘design new system architecture’. One day I can complete a dozen tiny tasks, but the next day I could spend the whole day on diving deep into some problem. Does it mean that the day when I completed 12 tasks was more productive than they day when I comleted just one? Does not seem right to me.

Leave it subjective

I often see people just using a subjective measure of productivity. I can use ‘It feels good’ or ‘I could have done better’ to determine productivity. While it may be pretty accurate if I am self-critical enough, it is hard to keep unchanged over time. Today my perception can be different from yesterday’s. If I just came back from vacation, caught up with emails might feel good on that particular day. But how do I compare it to a day when I fixed a critical bug or designed system architecture? It would be different ‘feel goods’.

Use other abstract units

There are some techniques that aim to improve personal productivity, such as the Pomodoro Technique. The short idea is that you split your day into fixed-time chunks (called “pomodoros”) when you do nothing but focus on your tasks. In the end of the day, you can count completed “pomodoros”. The more pomodoros I complete - the more productive I am in a given day. This approach seem to be closer to the truth. No meetings or phone calls are allowed during a “pomodoro”. Since a “pomodoro” is entirely dedicated to working towards your goals, so it seems that number of pomodoros can directly translate into productive time. Almost. There is just one important piece of information missing - what is inside the pomodoro? What do you exactly do during a pomodoro? For example, if you spend the entire time reading documentation or writing code - you are 100% productive. But what if you write code for 5 minutes, and then wait 20 minutes for code to compile or to run tests? Is this pomodoro can be considered just as productive? I don’t think so. Time spent waiting for something to happen (compilation to complete, webpage to load, etc) is a time not spent on doing something important, a time not spent directly on getting closer to your goals.

Measure time

What if it is the measure? If the amount of time I spend on something unproductive is a measure of “unproductivity”, then the rest of the time was spent productively, so it is a measure of productivity. The productivity is a ratio between input (time) and the output (progress towards goals). It is hard to measure the progress towards goal directly, as all tasks are not equal. But the input (time) is fixed. I can see how much of time I waste on things that don’t bring me closer to goals and compare to the time wasted. The more time spent productively and the less time wasted leads to greater productivity.

How to get the best of it?

I think it is very hard to quantify productivity. It is highly subjective and varies greatly day to day. There are many different approaches that you could take, but none of them is a silver bullet that provides the best answer. There are many things that affect our productivity. They can steal our time or give it back to us. And all of them snowball quickly into drastic differences in productivity. I think that a very effective way to understand one’s productivity is to be mindful of it. Keep it as a clear idea and try to understand what affects it.

Doing More With Pomodoro Technique

Igor Fil — Tue, 12 Jan 2021 17:10:34 +0000

Wishing you had one extra hour every day to get more done? Probalby yes. Would you be even more productive if you had 30 hours a day? It seems so, but, actually, I am pretty sure that the answer is negative.

The most intuitive idea is that if you had more time you would get more things done. We tend to believe the intuition that if we had twice as much time, we would be able to produce twice as much output. If humans were machines, that would pretty much be the case. But humans are not. We don’t scale linearly. Our brain just does not work that way. Can we try to get more with less? Produce more with less time?

Where is my time?

Try to look at your regular day. The minute you start doing something productive, you are getting bombarded with notifications from all angles. All those countless apps compete for your attention. That’s how they earn money. And that’s how you actually lose it. Every time you check your email or notifications that your phone desperately pushes in your face, you lose precious time. That is the time when you are not doing anything productive. You get into a cycle of switching your attention back and forth between the important things that need your attention and the unimportant ones that want it.

I experienced exactly this same pattern day after day, getting increasingly frustrated. Those little things that distract you feel harmless, but in fact they are vicious animals that eat your time. It is so easy to get caught, starting with innocent email and ending up scrolling through the endless depths of the Internet.

The problem is not only in those little distractions. A bigger problem is that our brain cannot switch tasks immediately. It needs some time to switch context (just as CPU needs some time to switch between tasks and load data into cache). That time added on top of those little things increases time waste dramatically without us actually realizing it.

Get out of my cave!

OK, so we are strong people who can isolate ourselves from distractions (right?). Let’s mute the phone, turn off email notifications, close the door, and just do our work. Feels better, right? You work non-stop for several hours, arriving to lunchtime with plenty of things done (code written, etc). But what is that feeling in your head? The head feels heavy and the thoughts are slow, just like after a long exam. After getting back from lunch you notice that the work you did (code you just wrote) is total garbage and you need to spend just as much time overhauling it.

Does it look familiar too? What happened? I am not a “brain expert”, but I think you would agree that it is important to keep brain fresh. Focusing on one thing for a prolonged period of time gets brain tired and develops a tunnel vision.

Tomatoes come to rescue

Did you ever notice that taking a break from solving a hard problem and switching to something else, like taking a walk, gives you a new angle on the old problem and reveals solution that seems obvious, but was not apparent before? This is the essence of Pomodoro Technique - alternating periods of extreme focus, when you focus only on your tasks, with periods of rest - when you switch your attention to something completely different and give your brain a chance to refresh.

Develppped by Francesco Cirillo, the technique uses a timer to break down work into intervals, traditionally 25 minutes in length, separated by a short break. Each interval is known as a pomodoro, from the Italian word for ‘tomato’, named after the tomato-shaped kitchen timer.

When using this technique, you completely focus and your task for 25 minutes, ignoring any distractions. After 25 minutes, you take a 5 minute break, when you can check Instagram, go for a walk or coffee - anything that helps your brain to get refreshed. Then, get back to work and so on.

Another benefit that it provides - it makes it easier to make your productivity quantifiable. You can count how many pomodoros you did in a day. One pomodoro is 25 minutes, plus 5 minute break. It means that in a typical 8-hour work day you would expect to pull 16 pomodoros. Try it yourself. You might be surprised that the number is nowhere close. In my experience, while working for a huge corporation, with countless meetings and a big open office, sometimes I struggled to complete even 6 or 8 pomodors a day! It means that less than 50% of my time was actually productive. After a few weeks of following pomodoro technique, I was consistently over 10.

Use Caution

There are hundreds of books written on productivity and countless seminars are held each year. There are multiple productivity techniques that really work and I am sure you have your favourite one. But they are not silver bullets. They can’t magically transform you from a slacker to achiever. It is all in your head and your attitude. These techniques are there just to help you.

Also, you need to be mindful. Don’t get too far. The work is not only about how many pomodoros you can accomplish. You should not get overly obsessive with pomodoros. It can lead to anxiety and wrong priorities (just writing code, completing more pomodoros, rather than attending a design meeting where you might understand that this code you are writing is not needed).

I practiced pomodoro technique for a few months. It helped me to develop an ability to focus on my tasks and to turn off distractions. Additionally, it trained me to take breaks from my work. Now, I don’t even need a timer - I developed a habit of taking breaks to refresh my mind; it feels like a second nature. It is great to use techniques, like Pomodoro, that help you develop new habits. But they should not be followed blindly. Take the best out of them, while staying rational and mindful.

A Subtle Art Of Writing Good Code Comments

Igor Fil — Mon, 28 Dec 2020 18:30:28 +0000

Today I want to explore somewhat overlooked topic of code commentaries. It seems like a simple topic, yet it is the one that sometimes invokes the hottest water cooler arguments! But why do we debate about it, why do we understand it differently? What is a bad code comment and makes a good code commentary? Why do we write code comments in the first place?

Some argue that code must be self-explanatory and there must be no code comments at all, that code comments are a sign of badly written code. On the opposite side of the spectrum is “comment every line” camp, those who insist on extensive comments of every piece of code. But where is the right balance?

Over the years everyone has seen lots of code comments. Some of them were really useful, others were useless, while some were utterly harmful. Looking at those, everyone has developed his vision of what code comments should look like.

Let’s take a look at some examples.

Useless comments

Sometimes code comments doen’t bring any value. They don’t seem to add any additional information and seem to be only exploding line count.

For example:

A comment that states the obvious

/* Sets price */
public void setPrice(int price) {...}

Such comment does not bring any additional value. It just re-states something that is already obvious from a function name.

Comments on every line

// validate request
validateRequest(request);

//extract data from request
SomeData data = request.getData();

//Process data
dataProcessor.process(data);

Such style of commenting is a variation of the previous one. It usually starts with good intent to explain every step of the process. But in this case using good naming convention and Single Responsibility Principle gets you all the way there. Splitting big chunk of code into smaller functions with clear name and sole purpose gives not only provides you with such step-by-step explanation, but makes comments useless.

Arrange-Act-Assert comments in unit tests

public void testGiveNullReturnsEmpty(){
    //arrange
    Converter converter = createDefaultConverter();

    //act
    Optional<SomeComversionResult> result = converter.convert(null);

    //assert
    assertTrie(result.iEmpty());
}

Following Arrange-Act-Assert structure of unit tests is a great idea. But conventionally this separation in code is achieved by using a new line between sections. This is a common practice and anyone familiar with this pattern will recognize it immegiately. Stating them explicitly does not add any clarify, just adds clutter.

Harmful comments

Sometimes code comments can bring more harm then good. They can confuse or mislead.

Clarification of what variables mean

// time delta
private long t_d;

Typing "t_d" might take less keystrokes, yes. But it requires much more mental capacity to process! Every time you read variable names like that, you need to make mental conversion into what it really means. And if there are multiple variables like that in a piece of code, especially with similar meanings, the amount of cognitive load grows exponentially. Why not call variable "timeDelta" in the first place?

Outdated comment

// Returns time in UTC
public DataTime getLocalTime() {
    return localTime;
}

The biggest problem with comments is keeping them up to date when code evolves. It often happens that while code is changed, comments are unloved and forgotten. As a result, code might have rich comments that are artifacts of the past, showing what used to be there but no longer present. It is absolutely useless and very harmful.

To-Do comment

// This is a temporary hack. Will be removed at the next iteration.
// This code should have never been committed.

Such comment is and indication of a major technical debt. I was surprised to see such thing in a major piece of code that constitutes the core of business logic. Especially, noticing the fact that it has been committed over 8 years ago. We all have deadlines and sometimes taking shortcut is the only solution. But important here is having a discipline and pay off technical debt a soon as possible. Otherwise, there will be other shortcuts applied on top of that shortcut and tech debt will grow like a snowball. Bottom line - To Do items don't belong to code, they belong to a task board.

Implementation details comment

// Calculates shortest path between points using
// A* algorithm. It starts with ...
public List<Node> calculatePath(...) {}

Implementations change. Interfaces persists. Using comments to describe implementation details is like planing a time bomb. This comment will become obsolete, it is only a question of when.

Misleading comment

// Does one thing
public void doSomething() {
    doTheOtherThing();
}

Such comments claim to clarify what a piece of code does, when in fact it does something else. Usually it is also a leftover comment that was not updated as code evolved.

No comments at all

class Record {
    private String marketplaceId;
    private String merchantId;  
    private String isbn;
    private Money retailPrice;
    private List<Schedule> schedule;
}

Sometimes you can stumble upon classes with generic names and a collection of fields that don't tell anything. It is unclear what such classes represent, why they exist and what those fields mean.

Documentation generation

/**
 * Sets the value of the field "isbn" to be used for the constructed object.
 * @param isbn
 *   The value of the "isbn" field.
 * @return
 *   This builder.
 */
public Builder withISBN(String isbn) {
  this.isbn = isbn;
  return this;
}

I am likely to be in minority when it comes to comments that are used to generate documentation (for example, JavaDoc). While I can understand the good intention, I find it having a big downside. First, this is just a comment, it is used for generation of documentation, but it still needs to be updated to keep up with code just any other comment does. Second, sometimes such comments grow so big that they hide the actual code. I have seen some PoJos, where documentation comments took 75% of space, making it hard to see the code itself.

Comments that create value

Some comments can useful and bring actual value. They can explain things and help to avoid ambiguity.

Clarify the intent

// A database record for a book. Core book entity to be used to persist any
// data associated with a book. 
class BookRecord {...}

Such comment does not go deep into details, it does not say anything about implementation or type of database to be used, or about class internals. All those things might and will change. Comment will stay relevant, its goal is to clarify why this class exists, not what it does or how.

Provide meaning

// Book discounts. Maps book ISBN -> discounts available for the book
Map<String, List<Discount>> discounts;

Programming languages give limited tools to express the full spectrum of human ideas. Sometimes comments can be used to express ideas that we cannot express in code. For example, using String as a map key in example above does not give any context. But adding "ISBN" as its meaning makes it easier to build mental model. This in turn, facilitates development process and helps to avoid errors.

Start with why

There are multiple opinions on code comments. But let’s ask ourselves the most important question. Why do we write code comments? What is their function, why they exist? My own answer is that comments exist to express ideas that we cannot express with code. It is easy to express algorithms in code, states, sequences. In other words, it is easy to express what to do. Also it is easy to express how to do things. But what programming languages don’t allow us, is to tell why things exist. Why do we do things one way and not another. If we look back at examples above, it is easy to see a pattern. Comments that bring value and stay relevant over time complement code, helps to express ideas. Say why. On the other hand, the comments that bring nothing, or bring more harm than good, get into implementation details, express things that we express with code. In other words, they say what and how.

I believe that the subtle art of writing good code comments that live long and bring value, is to use comments to say why, not what or how.

Summary

How Code Coverage Lies To You

Igor Fil — Wed, 23 Dec 2020 00:39:13 +0000

In my previous article I talked about why it is a good idea to write unit tests. Now I want to talk about a different question - how much unit tests to write?

How do we know when to stop writing unit tests? When we run out of ideas for tests? When we test all possible scenarios? When the clock hits 5 o’clock? How do we know that we have written enough tests? One commonly used measure is code coverage.

What is code coverage and how to use it

What is a code coverage? It is usually a number that tells you how much of your code is “covered” by tests. To calculate that number, testing frameworks just count number of lines of code that were executed while running a suite of tests. Then they just give a number, like 60%.

Code coverage is pretty useful metric, it allows engineers to get quantifiable figure and track it over time. It allows to compare apples to apples, we can see how many tests the code has now versus what it had in a past.

I often see development teams setting test coverage goals for their systems. Sometimes, code coverage number is used as part of a build verification process, failing the biuld if code coverage is below a certain threshold. Some say that they need at least 60% of code to be covered by tests, others insist on 80% code coverage, while some even go to extremes demanding 100% code coverage.

What is it telling us?

But let’s think of how do we interpret code coverage numbers? If the test suite passes, all tests are green - means our logic is correct, right? If those tests cover 100% of application code, it means our application is 100% correct, right? This is exactly a trap that I have seen people falling into. Following this logic, can we say that an application with 80% code coverage is 50% more correct (or has less bugs) than application with “just” 40% code coverage? Edsger W. Dijkstra argued that

“Program testing can be used to show the presence of bugs, but never to show their absence”.

Following his logic, our suite of tests will show that there are 0 bugs in the logic that we tested. It feels intuitive to extend this logic to say that it means that there are no bugs. But! It shows us that there are 0 bugs, in situations that we tested. It does not tell anything about those situations that we did not test in our suite.

“But wait!”, you will tell me, our code coverage shows 100% that means that we tested everything. But testing frameworks are pretty dumb, code coverage just count number of lines that you tested, not all logically possible situations. The will not count if you tested with all possible input data. It is absolutely possible to have 100% coverage, run every line of code, yet don’t test all logical situations.

How code coverage lies

Consider this primitive function as example (in no matter what language):

double divide(double a, double b) {
  return a/b;
}

and we have a nice test for it:

void test_divide(){
  assertEquals(2, divide(2/1));
}

Code coverage will be happy to report 100%! But what happens if b is 0? All tests are green and code coverage is 100%, but there are still problems in the code!

Now what?

So if 100% code coverage is not a good goal, then what is? It is a worthy investment of a very expensive engineer’s time to write tests to reach a certain code coverage number? Can we say that 40% or 60% is good enough?

Reaching 100% (or any very high percentage) is a very expensive and wasteful venture, just think of all those getters/setters that are present in modern OOP languages and their primitive logic! Even 60% or 40% can make little sense, depending on nature of your system.

Maybe code coverage does not matter after all?. Quality of tests matter much more than mere quantity. If for example, we take Pareto Principle as a guide, we can think that code coverage of just 20% should be able to catch 80% of problems. As long as the tests are good, their quantity is not important.

Be mindful

Overall, code coverage is a useful tool, but it can trick us into false sense of safety, or a goal of reaching high code coverage numbers can lead us to wasting valuable resources. We should not mistaken it for something that it is not. It is a good quantitative measure, not qualitative. In other words, it can show, how big the test suite is, not how good it is.

Why write unit tests?

Igor Fil — Sat, 19 Dec 2020 00:05:25 +0000

Why do we write unit tests? What do we expect from them?

I have heard many different opinions, sometimes quite opposite. Some may argue that unit tests are not that important, and sometimes are just a burden that prevents from moving fast. Others claim that they actually allow to iterate faster and they are more important that the code itself.

I think that the truth lies somewhere in between. When written poorly, unit tests will indeed will create obstructions, draw resources and slow you down. When done right, unit test suite will allow you to go fast and don’t look back checking if you have broken anything.

It takes skill to do it right, but first and foremost, it is crucial to identify what is the expected result, what do we want from unit tests.

In my personal experience, I have seen following benefits from good suites of unit tests:

Verification of correctness. The obvious way to check if code works is to run it. It is OK to manually run and verify the result as long as the application is quite primitive. As soon as it becomes bigger than several logical structures, manual verification is no longer a valid option. But we can use other code to run our code - tests. The test will run the desired piece of code and verify if it does what is expected.
Bug fixing. Test don’t fix bugs themselves, but they are the best tool to narrow down the problem and to ensure the fix works (and also that it keeps working in future). You can write a test for a piece of code under suspicion and make test validate if the result produced by code matches expectation. If it does - code is OK, if not - even better - the problem has been found. Now keeping the test in place, you can fix the bug and the test will tell you right away the problem is gone.
Better code structure. Writing tests is useful to split code into smaller, more meaningful functions with sole responsibility. Especially if you follow TDD, the code will naturally grow better-structured with proper dependency injection and separation of concerns.
Documentation and specification. Unit tests are a great tool for code documentation and specification. A good well-written suite of unit tests can tell much more about how code works. It clearly states what are the possible inputs and expected outputs. Moreover, a suite of tests will always be up to date, it cannot become neglected like a wiki page.
Facilitate changes and enable refactoring. It may sound counter-intuitive, but a good suite of tests makes it easier to make changes in code. Good tests verify only interfaces, not implementation details. It gives engineer an opportunity to change internal implementation and still be confident that the result is correct. As soon something breaks, the tests will tell exactly what. This makes a feedback loop very short. Unit tests allow to make changes safer and faster.
Communication. Unit tests is a great communication tool. As mentioned above, unit tests are a great documentation. And it stays relevant over time. A good suite of tests communicates author's intention, what the component does and to expect from it, both to other team members and to the author himself (try to remember intricate details of behavior several years after the release!).

Overall, in my experience unit tests proven to be an extremely valuable tool that gives me ability to build systems that are error-free and are easy to maintain. It may take time and require a paradigm shift to fully appreciate all benefits of good unit test suite, but the reward is great. A good suite of tests is a good investment that pays off in a long run.