Rapid prototyping

The last few months, I’ve been working on a set of WordPress plugins, related to event organization. With the help of AI, I’m able to get a minimal viable version of a feature that got to my mind in hours—which makes the whole development process more fun and faster. Before AI, I was trying to “measure twice and cut once” while programming—trying to minimize the waste, the expensive, development time. Currently, I’m building quick and dirty, first version with heavy help of Claude, and then I’m improving the code when (or if) I end up using it.

Easy technology switch

Use of generative AI makes it easy to switch technology. My professional experience in the last decade was mostly in AngularJS—an outdated, frontend framework. AI, allows me to start building things with other technologies, and learning while doing something practical—which is my favourite way of learning.

Priority shift from programming to solution building

AI makes the skill of speaking the machine’s language less important—right now, it can make the code that compile just fine in no time. But this doesn’t make the programmer’s job redundant—it just shifts the value to solution building. We can spend more time understanding the business case of users of our application, and spend less time turning it into code that can runs on a machine.

Conclusions

For me personably, the biggest shift is that as a sole developer, I can easily start building a solution and try turning it into a product. Things that before felt like a bit too much to chew for a team of one, feels much more reachable right now. The current technology opens a possibility to build and run a micro-SaaS, especially if combined with affordable prices for the customers.

Complexity

Things are always more complicated than they seem at first. Often we have unexpected complexity in two places—the problem we want to solve and the solution itself. As we try to solve the problem, we learn about new aspects that make it more complicated than it looked at first. And the solution that we create often becomes more complicated than necessary. This leads to way slower progress, to the point when the requirements change at the similar rate as the code itself.

Technical surroundings

No project is an island. Any functional piece of code depends on countless things over which we have no control. If you look with perspective long enough—5, 10, or 20 years—anything can change: operating systems, programming languages, or ways the IT economy is running. From a business perspective, plenty of efforts take many years to become profitable.

I started my career in 2008, and over the 15 years since I’ve seen:

• iOS (2007) and Android (2008) becoming important operating systems,
• the appearance of Node.js (2009) and its rise to popularity,
• Web platforms overtaking desktop applications,
• the growing popularity of JavaScript, and
• the disappearance of Flash and Java applets.

With changes of this scope, there is no way to create a future-proof project—at some point, you (or your successors) could be forced to rewrite everything on a new stack.

Third-party APIs

On a less dramatic scale, your application is likely to use some external providers: for managing payments, sending emails, or any other services. Given enough time, some of those providers will go out of business or rebuild their API and deprecate the version that you are using. Usually, there is some transition period, but it will likely be a few months rather than a few years. In a project with many competing priorities, this can feel like short notice.

Legal requirements

Similarly, the legal requirements can change from one year to another. In the EU, we had a big change with VAT and online sales in 2021. For many online companies, that meant plenty of changes in the code. They were forced to start dealing with VAT in every EU country that they were selling to.

The company where I work deals with brick and mortar businesses—we were not affected by online trade regulations. Nonetheless, we had an assumption in the code that there are only 3 levels of VAT—for example 0%, 7%, and 21%. This worked fine for us for a long time. It turned out to be a problem, however, when one of our customers expanded to a new country. Over there, not only were the percentages different, but there were also simply more levels. When you have to change a fundamental assumption like this, you are likely to get an avalanche of changes in your codebase.

Code dependencies

A mature JavaScript project has many essential dependencies:

• the framework it uses
• unit test library
• end-to-end solution

Creators of those tools try to smoothen the upgrade path as much as possible, but they have a trade-off between the ease of upgrade for you and how much they can change. And when the tool is discontinued, moving to a replacement is guaranteed to be a lot of work.

When I started working with AngularJS, Protractor was an impressive end-to-end tool—the best tool available for doing integration testing of angular applications, and probably for any frontend application. Now, 8–9 years later, it’s been a few years since it got an update, and in August 2023, it reached its end-of-life. There are better tools available now, but moving four hundred tests I have on Protractor would be a huge project.

Product discovery

Product discovery is a nice term that covers the fact that it takes time to find the right combination, where:

• your customers have a problem,
• you can address this problem at scale with an application,
• they are willing to pay for using your solution, and
• what they pay covers your costs.

You can expect this process to take time and many iterations. Some of the iterations will require implementing a feature and then seeing if it's useful to customers, and whether it makes money for the company. As long as the product is used, there will be some ideas worth checking.

How to manage it

So we know that the IT projects are unlikely to be done—that there will always be some changes that require updates to the code. What can we do about it?

Plan long term

There are always dead-lines to be met, but make sure that quarterly goals will not ruin the long-term future. Think about it as a marathon, not a sprint. One thing worth investing time in is code quality. Some compromise and flexibility will be needed, but think about overall architecture, consistency, and best practices of the stack you use. Rushing too much can lead to making a code so difficult to maintain that it will become impossible to make the simplest changes.

Document what you are writing. For a start, maintain a README file with instructions on how to start the project. Write documentation for classes and methods, preferably in a way that makes it easy to extract the documentation—for example, JSDoc.

Write automated tests. Unit tests slow down development when you are learning to test at the same time as you write code. Once you are proficient with testing, developing tests along with your code can be faster than the code alone. When you write code and tests together, you have a quick way to recheck all the edge cases you want to cover.

Keep the team around

Even with the best effort at documentation, there is a lot of knowledge that is stored only in the minds of your team members. What decisions were made 4 years ago and why; how similar bugs were fixed the last time; what code is responsible for what. Every time a team loses someone, part of this knowledge is irreversibly lost. It’s a shame the industry got to the point where changing jobs often is the best advice for developers. If you can influence that, it would make sense to make sure the devs are happy with the job and the conditions and stay as long as possible.

Developer experience

User experience (UX) focuses on how the user interacts with the system and makes their journey as smooth as possible. Similarly, we could consider developer experience with the system. Usually, in small projects, the priority of improvements that benefit developers is low enough to never be done.

The examples of good developer experience come from large projects and products targeting developers specifically—for example:

• Cypress for end-to-end testing,
• popular frameworks, such as Angular or React, or
• GitHub, CircleCI, etc.

Small companies, or one-person open-source projects, often lack the resources needed to make your journey pleasant. Simply, if you have to onboard a new developer once a year, it can be cheaper to have them struggle for a bit then to make the installation smooth.

Ever-growing complexity

Projects tend to grow in complexity with time. All the time, things are being added:

• new features
• refactorings that take forever to be applied on the whole codebase
• dependencies that become outdated

If you have a project that lasts for a few years, it will definitely be more complicated than something that would be written now.

The accumulated complexity often spills into troubles with starting up the project: you might find a mismatch of technologies, and they can interact in an unexpected way when you start the project on a new machine.

Documentation challenge

Explaining things in writing can be difficult, but this doesn’t often receive enough attention. Even if the team you join tries to keep docs of a decent quality, there is always one challenge left: they have to assume some level of knowledge in the reader. There is always a trade-off involved with that—when you explain too much, it will be more work to write and maintain the docs. Moreover, you could flood the reader with too much text. If you explain too little, the documentation will lack crucial information for some people.

Some common examples of things you could struggle with:

• Plenty of programming (C++, Node.js, Python, Git) and internet tools (Apache, Nginx) come from Unix-based systems—if your background is in Windows, then you will be struggling with some underlying concepts.
• Many programming tools are built with the command line interface (CLI) in mind: the most important is Git, but other tools are often important as well—ESLint, Prettier, etc. If you have never used CLI tools, you might have gaps in knowledge that no project documentation will try to address.

When I was starting to learn programming, I often got stuck on one or two sentences of the book that described a step I couldn’t overcome. Luckily, as time goes on and you gain experience, cases like this become less common.

Unexpected differences

There can be many differences between your machine and whoever builds the system you’re trying to start now.

Differences in operating systems tend to cause the biggest issues. Linux's distros and macOS are usually compatible enough to be considered one camp. On the other side, we have different versions of Windows. If you join a project that was built on an operating system very different from yours, then you are likely to discover some incompatibles that nobody expected. In JS projects, it’s often expected to be able to run it on whatever OS you like, but it can require some effort to make it truly compatible between systems.

Another surprise can come with the ways of installing tools you need to run the project. For example, last time I checked, Windows had three ways of installing Git—each method doing things slightly differently. Similarly, Node.js or Python can be installed in many ways on Unix systems, and sometimes developers forget about the ways that are different from their preferred one. I always use nvm to manage my Node.js, but it’s not what you find when you go to Node.js website to check for installation guides.

Containers to the rescue?

Containerization, which was made popular with Docker, makes it simpler to move across machines and OSes. Unfortunately, you would still be lucky to have your whole developer journey paved with well-prepared, ready to use images. At my job, I had a good experience using Docker as a shortcut to getting a backend up and running quickly locally. Nonetheless, I still struggle to move the whole developer experience to containers so that everybody has the same dependencies available. Containers are a great tool, but any work at optimizing developer experience faces the same lower priority that we mentioned earlier.

How to deal with it

Accept that it will take time. If your team tells you that the setup can be tricky, or that you can expect some issues—trust them, and don’t get frustrated.

Ask questions. I’ve seen more devs erring on the side of asking too few questions or too late rather than asking too many or too early. If you don’t want to be annoying, or just want to be somehow independent, set an alarm clock to add an hour or two and ask a question when it rings if you are still stuck. Then you can take your time to describe your issue well, following the tips I shared previously.

Improve the doc. Ultimately, try improving the experience for the next person that will take the same path. The places where you struggled are valuable indicators of where the docs are lacking. Maybe “install Node.js” needs more elaboration with respect to “from where” and “how.” Perhaps you are the first one to run the project on Windows, so you could help others take the same path quicker. In a way, during your installation, you become a beta tester of the documentation, and with everything running, you have enough experience to improve the docs.

What was your experience with getting onboarded on a project?

Please share in the comments—I’m truly interested in hearing how it goes for newcomers to projects.

Obvious entry points

When you start a ticket on an application, usually you have some information about where the change or fix should happen. You can make linking that place to the code easier if you consistently use some convention for naming and placing the files. Let’s take a look at a few examples.

Component-based app

In my day job, I build and maintain a few Angular applications that are built with components. Each application has many routes defined, and for each route there is a top-level component that is responsible for this view. The naming convention we use is as follows:

• simple route: /home-page—<home-page>
• nested route: /long/nested-route—<long-nested-route>
• route with parameter: /user/:id/edit—<user-edit>

In this way, if I get the route where the changes should happen, I can immediately find related component files.

Backend

On the backend, we have a few constraints put on the routes we use. The API is loosely inspired by the REST approach, and each endpoint is related to one of the collections that we have in the database. The routes are in a format /collection/operation—for example:

• /users/get
• /transactions/get-report

The code that is called by those endpoints is organized in files by the collection: so in one file we have methods related to users' collection and in another we have methods related to transactions. In this way, based on the first part of the API route, I know where to look for the code.

Avoid unnecessary jumps

One of the ways that I often see makes the code complicated is by sending the reader through many unnecessary jumps. When you read code, it’s inevitable that you will need to do some jumps between different parts. This becomes a problem when the jumps are many and unnecessary. Some examples based on what I’ve seen in real-world code:

• a function that does nothing besides creating an alias for another function

function A(param1, param2) {
  return B(param1, param2)
}

this can make sense for some refactoring, but it would be good to have it in a temporary situation,

• named callback functions defined away from where they are used:

function success() { /*..success..*/}

function error() { /*..error..*/}

getPromise().then(success, error)

The same thing would be simpler to read if it were:

getPromise().then(() => { /*..success..*/}, () => { /*..error..*/})

• expectations in a test set in variables, away from where they are used:

const expectedObject = { /*..some big object..*/ };

/*..many lines of code..*/

expect(result).toEqual(expectedObject);

Whenever we have a jump in code, we make it slightly more complicated to read. Let’s make sure that this inconvenience is balanced by some benefit—that there is a good reason to do it this way.

Keep it simple

The flow of your code should be straight. It should be easy to draw a chart of how the logic flows through the application and how things depend on each other. There should be no circular paths in your code, unless you are doing some recursion on purpose.

It should be your goal to be always able to explain how user actions or some external events lead to data changes. If you cannot easily tell what is responsible for what, then it’s very likely your code is chaotic and difficult to follow.

Displaying data

Of the simple cases is transforming the data for display. It could be one of many things:

• formatting dates in a user's locale,
• translating into user’s language,
• combining many properties of an object into one, ready to display string, or
• filtering an array based on a search.

Each of these operations should have an easily identifiable input and output format and should be written in a form such that a reader knows what goes in and goes out.

Formatting data for display should leave the original untouched—there is no reason to change the data just because it is displayed in some place.

Changing state

When you change the state of your data, it should be possible to easily identify the following parts of the code:

• source of the change—button that was clicked, the event that occurred in the system, etc.
• the change itself—the code that checks the constraints and updates the state of the data
• saving the changes to the storage—this could be an update to the database in the case of backend code or calling a save API in the case of the frontend

If, for some reason, it’s not easy for you to identify what parts of your code are responsible for some of those points, then reading this code will probably be pretty confusing.

Testability

All the things we discussed here are consistent with writing testable code. Small, well-defined units with clear responsibilities are easy for developers to understand—and easy to test. For me, writing tests is a good exercise that can teach you to write more readable code: just pay attention when testing starts becoming painful and when the code becomes too convoluted to easily work with.

Learn more

If you are interested in hearing from me when I publish some new material about programming or related topics, you can sign up for my mailing list.

Building blocks

To simplify our discussion, let’s focus on what we have available in JSON—the data format that was created based on how data can be hard-coded in JavaScript. In this way, we don’t need to think about the performance implications of different data structures—we only focus on the usefulness of the data model.

Primitive values

These are the most basic value types we can have in our program. In JSON, those values are:

• boolean—a true or false value,
• a number—a floating-point value,
• string—a sequence of letters, and
• null—a missing value, which is still useful for expressing certain states.

Already with those basic types, we have the possibility of addressing the same thing in different ways. For example, for customer type, you could use some of the following:

1. const customerType = “retail”;—which could accept any other string value, both valid or invalid ones
2. const isRetail = true;—a more rigid approach: its two options are obvious and clear, but it has no way of allowing more possibilities
3. const customerType = 2—can be expanded, but requires documentation for understanding what each number means

Anything you decide will impact how easy it will be to change code later on. As you are picking the value type for your variable, it’s good practice to try to think about possible changes and pick a type that fits well for both current and future needs.

Arrays

Arrays are ordered lists of values. The JavaScript arrays can mix any types of values, for example:

const someArray = [ 1, 2, “test”, [“another”, “array]];

Although it is a valid array, mixed types arrays are confusing to work with. It’s way easier to stick to keeping the same types of values in an array.

An important feature of arrays is that they are ordered. This makes them a great match for places where you care about similar data points and where the order is meaningful. For example:

• products in cart—you definitely want to display items from a cart in the same order; and
• students in a class—each one of them has their list number.

Arrays work well when you access many values in sequence. It’s less useful when you want to find whether a given value is in an array. When I find myself often using includes() to see if an array has some object I’m looking for, I take it as a potential sign that I should reorganize the data structure.

Objects

The object is a structure that consists of a set of key–value pairs. The structure is unordered, so it makes it a suitable choice for many places that don’t fit the array. Each value on an object can be understood independently of all the rest, so you can mix different types of values without worry. Example of an object:

const user = {
  login: “lorem.ipsum”,
  email: “sin@dolor.com”,
  age: 24,
}

Objects are a good match for collections of named, unordered properties. For example, a set of permissions:

const hasAccessTo = {
  blog: true,
  blogAdmin: true,
  userAdmin: false
}

Built-in objects

JavaScript provides many object types that you can use on the code side to keep your values in a more suitable form—and with methods that make them more usable. For example:

• Date—for date time values,
• Set—for unordered collections of unnamed values that don’t repeat, and
• Symbol—a non-string identifier that will not collide with other values.

Those types are very useful, but in communication that goes through a web API that uses JSON to represent data, they all will be serialized to value types described above. In my daily job, where I program business applications, the only types that I use regularly are dates.

Pick the appropriate structure

The way we organize data impacts what can be easily done in our code. Let’s take a look at the permission example from above:

const hasAccessTo = {
  blog: true,
  …
}

This value can be used easily in conditional cases such as: if (hasAccessTo.blog).

The same requirement for a permission list could be met with another data structure:

const permissions: [{
    resource: “blog”,
    access: true,
  },{
    resource: “blogAdmin”,
    access: true,
  },{
    resource: “userAdmin”,
    access: false,
  },
]

The same condition from above would need to be replaced by:

const blogPermission = permissions.find(x => x.resource === ”blog”);

if (blogPermissions?.value) {
…

This is much harder to read, and it’s easier to write code that will throw errors in some specific cases. By using arrays, the only thing we “gain” is the order of permissions, which shouldn’t matter.

Create a draft

There are plenty of things to consider as we organize data in our codebase, and calls can get complicated pretty quickly. To avoid rewriting code, it makes sense to create some form of draft for the structures. In my case, I often describe them with the names I plan to use in the tickets I’m going to work on. Often, when you see your structure design written down, you’ll notice some issues with it.

Keep on improving

The data structure for your code will never be finished—it should keep evolving with your application. Changing names after they appear in many places in code, and in databases, will be painful. However, it is necessary because otherwise the mismatch between names and their current understanding will only grow as things change over time. This is a common source of code debt that often slowly piles up until it makes working with the code an unpleasant and unproductive experience.

Learn more

If you want to receive an occasional email from me about programming or related topics, you can sign up here.

One name for one thing

For organizing our stuff, the general advice is to have a place for everything and everything in its place. Similarly, our lives will be much easier if all the people involved in the same project use the same terminology. Usually, we developers don’t have a perfect understanding of the domain in which the project is used. As a result, it makes the most sense to learn the terminology that is used by our business colleagues and use it in the code as well.

Parts of speech

To create terminology that is easy to use, it makes sense to apply some of the grammatical knowledge we all got from school. Different types of words fit better in different use cases:

• nouns are a perfect fit for objects or primitive values: user, accountNumber, customerEmail
• adjectives work great for some Boolean flags: allowed, disabled
• verbs match functions or object methods user.login(), shutDown()

You’ll likely find cases where it would make sense to bend this rule, but for me, it makes sense to try tweaking the names to match this pattern. For example, for a method that checks the current state, I would use user.isActive() instead of user.active().

Avoid abbreviation

I’m always skeptical of abbreviations as names in code. Many abbreviations are obvious only when you are deep in the context of the code. A reader who is new to the code and the domain can be confused. Making names short doesn’t improve meaningful metrics. When we write code, we usually use code suggestions, and most lines fit on the screen anyway.

When there is potential conflict between brevity and clarity, I always prefer to stay on the side of clarity. The only abbreviation I can think of now that I’m OK with seeing in code is VAT. It’s so commonly used that it is easier to understand than its expanded form: value added tax.

Pronunciation

All names we put to code are used in two ways. In writing—in code or documentation, and in speech—and when we talk about them. It’s important to think about both use cases when choosing the name. Pronunciation is often another reason to avoid abbreviations: they often miss vowels, and you may need to say it letter by letter.

Avoid name collisions

Try not to reuse the names with different meanings in other contexts. If you use some synonyms instead, then it will be easier for developers to intuitively understand the terms correctly when they hear it—without overthinking about the context in which they were used.

Brainstorm ideas

I have a high bar for naming things. Some names are easy to create; others are more difficult to come up with. For the most complicated cases, I try to write down as many ideas as I have in the ticket that will introduce a given concept to the code. I try to generate about 3 to 5 ideas—if it’s very difficult, I write down even the ones I don't like. With this in place, I ask my colleagues for their opinion. In this way, I get an external input and spend more time on thinking about the name. It helps in making the decision.

Newsletter

If you want to get occasional emails about programming or related topics, you can sign up for my newsletter here.

Tweak query

The easy way to start testing any API is to find an example that works—and then tweak it. You can pick any website and see what requests it does. For example, when you open developer tools in Chrome and reload my blog at how-to.dev, you can see plenty of requests sent by the website:

In the list, we have a few types or requests:

• script or stylesheet with names 4421.a65a… or 6238.6ee7…,
• fetch with names such as user, tags, events,
• xhr with name event,
• and some other types with resources: svg, avif, font.

We are the most interested in fetch and xhr request types. Both could be triggered from the JavaScript side and used for talking to the web API. The other requests we can see here are requests to load some static files—the code or some media content. For each of the queries we see on the list, we can copy one of the formats:

Copying the code allows you to easily do one of two things:

• rerun the query exactly as it was done by the application, or
• tweak the query to see how the API works with different input.

Fetch

Fetch is a JavaScript interface to communicate with servers—for example, to talk to a web API. You can read more at MDN. Here we will see our example query:

fetch("https://how-to.dev/api/user", {
  "headers": {
    "accept": "application/json",
    "accept-language": "en-GB,en-US;q=0.9,en;q=0.8",
    "baggage": "sentry-environment=vercel-production,sentry-release=736267205a61e0548a85c08aab089d3f1421126b,sentry-transaction=%2F%5B...slug%5D,sentry-public_key=0fbf92e944b8468cb9706e15c488c84e,sentry-trace_id=a2a1dbab6f5b4c619173000812050469,sentry-sample_rate=0",
    "content-type": "application/json",
    "if-none-match": "\"as45c9ut8od\"",
    "sec-ch-ua": "\"Not/A)Brand\";v=\"99\", \"Google Chrome\";v=\"115\", \"Chromium\";v=\"115\"",
    "sec-ch-ua-mobile": "?0",
    "sec-ch-ua-platform": "\"macOS\"",
    "sec-fetch-dest": "empty",
    "sec-fetch-mode": "cors",
    "sec-fetch-site": "same-origin",
    "sentry-trace": "a2a1dbab6f5b4c619173000812050469-8d225d0201152147-0"
  },
  "referrer": "https://how-to.dev/what-is-an-api",
  "referrerPolicy": "origin-when-cross-origin",
  "body": null,
  "method": "GET",
  "mode": "cors",
  "credentials": "include"
});

As you can see, there are a lot of details. To run the query, paste this code in the console in dev tools and add .then(console.log) at the end of it. The fetch function returns a promise, and adding console.log as a callback will show us the output right there on the screen.

You can modify any of the parameters provided to the call, and in this way you can see how the API will behave.

The big advantage of this approach is that you will reuse the credential information already available in your browser. If you have an open session, there will be a cookie in your browser, and it will be sent with your request: in this way, the server will know you are you, and where you should be given access.

GET request

Another option to test the API is to put the URL where you want to send your GET request into the address bar. By default, the browser does the GET request to the endpoint and displays the response on the screen. It will not always work as expected: in some rare cases, the API can be flexible enough to support different formats depending on the query headers. In such a case, it may be that address bar requests show HTML, whereas the API call gets JSON.

Demo API

Httpbin is an example API we can use for our testing. Its main page is some documentation that shows all the endpoints available for us:

Let’s try visiting some of the endpoints directly from the browser.

Address bar

When you open one of the endpoints http://httpbin.org/uuid you will get a response similar to this:

You can see more details by opening the dev tools and the network tab. When you refresh the page, you can see all the headers that were sent and received by the browser:

You can use this approach to test GET requests to web APIs.

POST request

Creating a POST from scratch is more complicated. You could try writing fetch calls, but as you saw earlier in this article, they can be quite complicated. Let’s use an API testing tool instead.

Hoppscotch

Hoppscotch is an API development tool that we can use to send any type of request—POST included. If you’ve heard about Postman, this is an open-source alternative. For the testing, I’ll send a POST request with some JSON data to Httpbin’s POST endpoint. At the initial screen, I set the URL to http://httpbin.org/post, the method to POST. In the Body tab, I set the Content Type to application/json and the Raw Request Body to:

{"test": 123}

Here’s the request just before sending:

The initial attempt fails because we are accessing an external server. There are few options to address it, with Proxy being the easiest to get you off the ground:

The result after retrying the request:

As you can see, the Httpbin API just returns a bunch of technical information about the request and the body.

This simple test skips the issue of authorization—many POST requests are only available to the user that is logged in on the server and fail for anonymous users. Covering this concept fully is a topic for another article.

Want to learn more?

If you are interested in learning more about API or related topics, you can sign up for occasional emails from my newsletter.

Demo project goals

A demo project is a good opportunity to show off the wide range of your skills. You can do this the best by expanding your project in depth—having a simple set of features for the application but implemented with high-quality code. With a simple feature set, you can focus on showing all the aspects of programming that you would like to work with. With a demo project, you have an empty canvas you can fill in as you please. The only constraints are your creativity, skills, and how much time you want to put into it. You can use it to show the breadth of your knowledge.

While working on a demo project, you don’t have to follow guidelines imposed on you by other developers. You can use this opportunity to show exactly what you mean by good, quality code. Quality is something that good workplaces pay a lot of attention to. Even in places where they say we have no time for quality code, it’s very likely that the technical interviewer will prefer people who can deliver maintainable code.

By delivering a demo project, you prove that you can ship something. Any project that is completed is perfect proof that you both have the skills necessary to create it, and that you are not a perfectionist who can’t finish stuff. Both things will be valued in a workplace.

Side goals

It can be tempting to add some side goals to the project to make the time investment more worthwhile. Depending on your situation, this could indeed be a good idea, but keep in mind that by adding additional priorities, you either water down the original purpose of the project, or you increase the scope of your undertaking. If you are thinking of applying for a job soon, try starting simple with technologies you know and add the new ones later on—if you have time.

Project scope

Building a project from scratch is always a lot of work. Typically, projects go over the initial budget estimation: just look at any construction project in your area. If you follow my advice of demonstrating many of your skills, you will already have a lot of work to do. To avoid starting a project that is bigger than you can finish, the best idea is to keep the feature scope as little as necessary. You can always expand the feature scope in the following iterations—exactly the way you do in agile. If you want some inspiration for simple demo projects, here you have a few examples of what I discussed on this blog:

• a simple application to store a sequence of data points on energy consumption
• a hello world app

Frontend

As a frontend developer, I’m always focusing the most on that part. Even if your priorities are elsewhere, the frontend will be the part of the application the reviewer interacts with, so it makes sense to invest some effort in it.

Depending on your priorities, you can include different qualities to it:

• If your dream job involves UI/UX design, you can put in the effort to make it pretty. Otherwise, a standard UI framework or even no styled elements will be OK.
• If you aim for a frontend job with some framework, you can use this framework in your project. Otherwise, vanilla JS could be an interesting showcase for how you solve some common problems on your own.

Backend

For many applications, you will need some form of backend. Depending on your career goals, you can try some “serverless” backend from the cloud, or build a server for your application yourself. If you aim for full-stack or backend positions, this will be a great exercise. It will complicate a lot of your local and deployment environments, but it will bring your demo application to be much closer to real-world cases.

With backend and frontend work, you will be confronted with many aspects of development that are not present in a project that involves only the frontend. For example:

• mono-repo vs. poly-repo, a topic I discussed in another article
• true end-to-end tests where you check both parts of the app

Covering those aspects in the demo app will be a great way of showing your capacities to the interviewees.

Database

Adding a database to your project would be yet another level of complexity. If you aim for a backend or full-stack job, it would be a great opportunity for you to show your work across all the parts of the stack. When your focus is the frontend, it will probably make more sense to skip the database and just keep data in the server’s memory.

Technology stack

You will need many technologies to get your project up and running. Make sure to choose things that make sense together: use a combination of technologies that are often used together and avoid adding libraries that overlap with the features they provide.

If possible, try using tools you are familiar with. Learning new things will make you slower in creating the application, and it’s more probable that you will make some mistakes while using it.

What to include

When I review projects for other people, I focus on whether and how they approach certain aspects, which I discuss below. This list is my personal list, and others will put different weights on those things, but I’ve noticed many senior developers are paying attention to the considerations I mention here. At the same time, some of those things are things ignored by junior developers.

README

When I visit a project for the first time, I expect a README file that will quickly bring me up to speed with the project. A great example is at date-fns:

You can find more about how to write a good README in an article on my blog.

Deployed application

When you try to show what you can build, it makes sense to make it easy for people to see the application in action and play with it. This gives them a context that is helpful to understand the code and will demonstrate the scope of the project. Besides, deploying is a critical part of the project life-cycle, and it makes sense to show you can take care of that too.

If you build only the frontend, the deployment will be effortless: you can use GitHub or GitLab pages, or Netlify. Adding a custom backend or database will require more effort—the easiest would be to find an affordable cloud provider and deploy to the cheapest instances there. I liked the simplicity of the offer from Digital Ocean, but the details of the offering of those companies change every few months.

CI/CD

Continuous integration (CI) is a piece of your project’s infrastructure that checks whether everything is working as expected after each commit. Continuous delivery (CD) deploys the last version somewhere that it can be tested: in the case of a demo project, it could be to the main environment because you don’t need to create a production and staging split.

For implementing continuous integration and delivery, you can use an offering of your Git hosting provider: for example, GitHub Actions or GitLab CI/CI. Another option is a dedicated CI service, for example, CircleCI. All those solutions have similar capabilities, and for simple pipelines, it shouldn’t matter much which one you are using.

Setting up CI can be more time-consuming than expected. As you tweak the configuration, you often need to wait for many minutes to see the impact of your changes. Running the code on external machines makes troubleshooting more complicated.

Linter

Linter is a program that analyzes your code, looking for errors or potentially problematic patterns. Each programming language has some tools like this available. In my frontend work, I use:

• ESLint for JavaScript and TypeScript code,
• Stylelint for CSS and SCSS, and
• HTMLHint for HTML.

Those tools help to catch little, annoying bugs and teach you what structures in code you should avoid. They often have extensive configuration options, and can be expanded by plugins. I see no reason not to use them in any project, let alone a project where you have to show off your skills and dedication to the craft.

Code style

As a developer, you spend more time reading code than writing it. Making the reading experience pleasant is important, and many senior developers insist on keeping the code as consistent as possible. Luckily, we have tools that take care of applying the code style across the project. For the frontend, Prettier is a tool that covers all JS/TS, HTML, and CSS. You can read more about it here.

Unit tests

The goal of unit tests is to check whether the part of the application—methods, classes, etc. are doing the thing they are supposed to do. There are many tools in JavaScript that you could use for writing unit tests, for example:

• Jasmine
• Jest
• Mocha

You have probably heard about the importance of unit tests many times before. On my blog, I have 2 related articles: how to write unit tests for a practical guide, and what are the benefits of unit tests.

End-to-end test

End-to-end (e2e) tests check that the application works as expected all the way from the frontend through the backend and to the database. Those tests can be complicated to set up because there are plenty of moving parts—frontend, backend, database—and they all should work fine both locally and in the CI setup. Even though it could be difficult to get it right, those tests allow automating a lot of repetitive quality assurance (QA) work. Including them in your demo project can be a great way of showing you care about the quality and efficiency of the development team.

There are many e2e frameworks available: for example, Cypress, Playwright, and Nightwatch. Unless you have a specific reason to prefer some of them, for the demo project, I would use Cypress—it’s the most popular option. Even if the team uses other tools than Cypress, they will definitely recognize it.

If you are new to automated QA, you might wonder what’s the point of having unit and e2e tests in one project. Many teams create both types of tests, and I went through reasons why it makes sense in another article.

Codebase documentation

I already mentioned the README file that covers the main purpose of the project, and how to start playing with it. Besides this top-level documentation, it’s very helpful to explain briefly the purpose of the classes and methods you write. The best place to do it is in the code—so you can read and update the description as you work on the files. At the same time, it’s good to have the documentation available in other places too: as suggestions in your code editor or on a website other developers could access without downloading the code.

JSDoc is a popular syntax for adding in-code documentation to JS projects. It integrates with many different tools—good code editors will manage to parse it and use it for code suggesting, or it could be built static.

Meaningful commits

One of the things I pay attention to in projects is the quality of the commit history. A good project history has the changes organized in commits that make sense as a whole and are described in a meaningful way. Well-maintained code history makes it much easier to understand the changes when one reviews code and simpler to look for a reason why something was changed. Small commits, with related changes, are easier to revert if necessary. I wrote more about how to use Git repositories efficiently in a previous blog.

Want to learn more?

If you are interested in learning more about building projects or other development related things, you can sign up for an occasional email from me here.

What is a web API

The API is what applications use to communicate with each other. Sometimes, it’s part of the server-client architecture of one system. In that case, a frontend application gets data from a server that is developed and maintained by the same team. In other cases, we have a different company providing access to their systems for external developers. Web APIs are how applications talk to each other over the internet.

HTTP

HTTP is a protocol that is the foundation of the internet—when you open a website, your browser sends a GET request to the address you provided. Most APIs calls done by web applications as they run in the browser are done with HTTP as well. Let’s see the basic concept we have in the protocol.

URL

Every request that we send with HTTP is asking for a specific resource, identified with a uniform resource locator (URL). An example of a URL is https://how-to.dev/what-is-an-api, where we have:

• https—protocol, in this case secure HTTP,
• how-to.dev—domain, which points to the server that takes care of the resource,
• what-is-an-api—a resource on that server.

Request method

Each HTTP request contains a method that explains what the client wants to do with the resource in question. There are 9 methods defined in the protocol—some widely used, others pretty obscure.

When you type a URL into the address bar, your browser will make a GET request to the server and display its output on the screen. GET requests should get an answer from the server, have no side effects, and be safe for caching.

Another common method is POST—it’s sending data to the server and expecting an answer to what was sent. It’s not supposed to be cached because it often alters data on the server. As it allows for two-way communication, it’s very frequently used for web APIs. So when you save a comment on a blog, add a product to a shopping cart, or edit your profile, it’s all most likely going through POST requests.

Some web APIs use the DELETE method for requesting the removal of a given resource and the PUT method for doing updates. Others use POST for all requests that result in changes on the server.

Query parameters

Query parameters are additional information added at the end of the URL. The query string starts with ?, and after that, there are parameter=value pairs separated by &. They are often used in GET requests to pass information to the server.

For example, by doing a GET request to http://geodb-free-service.wirefreethought.com/v1/geo/countries?limit=5&offset=0, you have:

• v1/geo/countries resource at geodb-free-service.wirefreethought.com server,
• query string ?limit=5&offset=0, which sets limit parameter to 5, and offset to 0—names commonly used for paginated requests.

Headers

Each HTTP request and response contains additional, technical information in headers. In the case of request headers, a lot of it is added automatically by the browser. The browser adds headers based on its capacities and configuration, previous communication with a given server, and system preference.

Some examples of headers that a browser adds to the requests it sends:

• Accept:—to tell what data type the browser should expect as an answer, such as text/html for HTML files,
• Accept-Encoding:—to tell in what compression type the browser can deal with, for example gzip, deflate, br
• Accept-Language:—for the language preference, with weights, for example: en-GB,en-US;q=0.9,en;q=0.8

Other important information passed in headers is cookies. Cookies are set by the client or server, and while they are present, they are added by the browser to each request to a server with a matching domain. Cookies are often used to manage user sessions on the server.

In Chrome’s dev tools, you can see the headers in a long list in the details tab after you click some request you are interested in:

Response codes

A response code is a quick way of summarizing the result of the request. There are many codes precisely defined, but the most important are broad categories indicated by the first number of the 3-digit codes:

• 1xx—request received, still processing
• 2xx—successful request
• 3xx—resource redirection
• 4xx—client error–the request is invalid
• 5xx—server errors

The response codes are used by different layers of the application to decide what to do with the request. A response with status 200 OK will be cached by the browser or intermediary server. Status 301 Moved Permanetly will cause the browser to repeat the request to the new location.

Any tool that you use for inspecting the request will show it in a prominent place. For example, in Chrome’s dev tools, it is right in the second column in the network tab:

Response body

In case of successful GET requests, the body contains the resource that the client was asking for. In other cases, it can be the error page—for example, a 404 page for missing content. The simplest way of testing a GET request is to paste the URL in the address bar of a browser. For example, Chrome displays an API response from http://geodb-free-service.wirefreethought.com/v1/geo/countries?limit=5&offset=0 like this:

For POST requests, there are many different answers that could make sense in the body:

• some summary of the result of the action that was performed
• complete resource after changes that we requested

It’s best to check the API documentation to see what is expected. For example, a login call to the European Tertiary Education Register is documented to respond like this:

Authorization

Most APIs need to control who gets access to what. Even an API that exposes public data, such as the previously mentioned GeoDB, can require authorization to limit its usage according to the user’s privilege. Some common approaches to this problem are as follows.

Session

Often in client-server applications, we have a login when the server checks the user + password combination, and a session is created when they match. The session is stored on the server and linked to the user. The session identification is sent back as a cookie and added to every consecutive request. In this way, we exchange the credentials only once, but with every request, the server knows which user is talking to it. Based on this knowledge, it grants or prohibits access to the data.

API key

For accessing the 3rd-party API, we often use access keys. It is similar to a password, but we are supposed to add it to every request. Managing API keys in web applications can be tricky because if we send it to the code run by the browsers, it could be retrieved from there and someone could get access to the API in our name. To avoid this risk, we could use a proxy that allows the users with a valid session to access the 3rd-party API, without exposing the key to the outside world.

Data formats

To do successful data exchange, both client and server have to agree on a data format. In some APIs, it could be negotiated with request headers. In others, the server supports only one format, and the client has to adapt to it. There are many options available, but they all serve the same purpose, and most often the communication happens in one of the following formats.

JSON

JavaScript Object Notation—a simple data format, inspired by how to write a hard-coded object in JavaScript. It’s very common in web APIs—it’s easy to parse on the frontend side, and there are plenty of tools available to generate it in server frameworks. The format is verbose and easy for developers to read as well.

An example object looks like this:

{
  "lorem": "ipsum",
  "number": 12,
  "array": [
    "sin",
    "dolor"
  ]
}

XML

Extensible Markup Language is another data format that could be used by an API to transfer data. It can be used on the web, but it’s a bit more of an awkward format than JSON—instead of getting plain objects, we get nested nodes that can have attributes. It became popular much earlier than JSON, so now it’s often used by older applications.

Example XML:

<lorem>
  <ipsum />
  <sin dolor="1">
  </sin>
</lorem>

API architecture

There are countless ways the API could be structured, and with good documentation, each approach could be equally useful. At the same time, there is a value in reusing good patterns between projects—you can reuse some code, and developers have it easier to switch between projects. Some noteworthy API architectures are below.

REST

Representational state transfer—its formal definition is well summarized on Wikipedia, but the term is used somehow loosely. A REST API should expose different URLs for different resources and use different request methods for different purposes—GET for loading, POST or PUT for data manipulation, and DELETE for removing.

In REST, the server provides the data in a format it decided relevant, and often we perform many requests for related data, for example:

• we query /user/123 endpoint to get users details,
• and we query /orders/?user=123 to get all orders placed by the user.

Years ago, REST was a buzzword, and REST APIs were seen everywhere—to the point that the term was overused. You even got models to evaluate how close an API is to the actual REST idea. When I hear some API is RESTful, I assume that there will be different URLs for different resources, and that most likely the data will be available in JSON format. For the rest of the details, I’m checking in the API’s documentation.

GraphQL

GraphQL is a language for querying and manipulating the data. It’s well defined, so any API that claims to use it should use it the same way. Some of the differences between it and REST are that all the communication happens at the same URL, and it’s the client that is in charge of deciding what data it needs—combining many related objects in one request.

This approach helps with:

• limiting the number of requests that go over the network,
• limiting the fields that are requested to only what is needed by the application at that moment, and
• smoothing the transition when some new fields are added to the object.

A short and to-the-point example from the GraphQL’s website:

Interested in learning more?

Sign up here to receive an occasional email with learning resources for programming and related topics.

Definition

API is the abbreviation for application programming interface. Those words alone probably don't help much, so let’s see what each of them means here.

Application

Applications are programs that provide some feature(s) to users. They store and retrieve data, perform calculations, etc. Applications give us a reason to use computers at all. The direct usefulness of applications contrasts with programs that we run to access other programs, for example:

• we use the operating system to open applications, and
• we use browsers to access web applications.

Interface

The interface is an exposed part of an application, prepared to receive input from the outside. As a user, you maybe already be familiar with some types of interfaces:

• graphical user interface (GUI)—the most common interface that we all know from personal computers and mobile devices.
• command line interface (CLI)—where the user types a program name and parameters to run a program.

Programming

An API is an interface that is meant to be used by other programs. So, instead of exposing buttons or menus, the application provides a way of interacting with it in a machine-friendly way. Nowadays, it is typically understood as a Web API—an online server that exposes different routes and returns data in a format that is both easy to parse for a computer and understandable for humans.

The name itself doesn’t imply any specific channel of communication—there are other types of APIs as well. On the web platform, we have an ever-growing list of APIs exposed to JavaScript by the browsers. The way of accessing differs, but the method is almost always rather rigid and requires precise interaction with it.

Intuition

APIs are simply a way for applications to communicate with each other. Good APIs are stable—because a breaking change in one application will require an update in all applications that use it. And good APIs are documented—because otherwise it’s very difficult to write a program that uses them.

Examples

Let’s take a look at some examples of APIs that you could play around with.

URL

The URL (uniform resource locator) is a form of an API. As users, we usually use them without thinking much about them. We use a web browser to fetch and display a website from an address that we clicked as a link. With well-designed addresses, we can tweak them and get still get a response from the server:

• when we replace the Netherlands part of https://en.wikipedia.org/wiki/Netherlands with Belgium, we get a valid URL: https://en.wikipedia.org/wiki/Belgium
• Some URLs are organized in a nice hierarchy. If we remove parts of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Numbers_and_dates, we go up to:
  • A list of JavaScript guides,
  • general JavaScript page,
  • Main page for web platform documentation.

A well-designed URL system invites us to tweak the address but will not help much if we ask for a page it doesn’t have. For example, when we replace JavaScript with TypeScript, we get https://developer.mozilla.org/en-US/docs/Web/TypeScript:

Playing around with URLs can be a simple way of trying out communicating directly with a machine—and getting used to their requirements of providing the parameters in exactly the way they expect.

Command line programs

Another simple way of starting with APIs are command line programs. Similarly to web APIs, the first step is to read the documentation. Then, make a few trial and error attempts at getting the program to do what you want it to do. In another article, I provide a simple introduction to CLI programs.

Web API

As a tester or a programmer, you are most likely to use a web API. They are relatively easy to use, but there are some difficulties involved:

• the access can be limited to authorized users—each system will have a different way of authorization and can require creating a user, logging in, providing the session information in cookies or some ID and key pair
• without getting too deep, you can do only GET requests—by pasting the API address into the address bar of your browser. The other types of requests (POST or DELETE) will require either getting some specialized program or writing simple JavaScript in the developer tools of your browser.

Let’s see some examples of APIs that you could experiment with:

• Open street map,
• Mastodon,
• Wikipedia.

What you can do with APIs

The main use of an API is to call other applications from the program you write. You can use them to leverage other systems for any variety of functionalities:

• OAuth for authorization with 3rd-party providers such as Google for Facebook
• getting automated translations from the cloud
• getting geolocation from map systems
• automatically cross-publishing the same content on many social media platforms
• accessing large language models to provide some AI functionality
• and many more

In a way, a lot of modern programming is writing glue code between different APIs.

How understanding APIs helps you debug

Because so much programming is about calling APIs, there is a lot of troubleshooting that can be done there. Many bugs I created encountered in my frontend programming career were caused by either

• sending an incorrect request to the API, or
• interpreting the response incorrectly.

If the frontend sends a valid request and displays the response as it should, then the bug is probably on the backend. If you can troubleshoot that much as a tester, this can significantly speed up finding and fixing the bug.

Learn more

If you are interested in learning more about APIs, programming, and testing, sign up here for an occasional email from me.

• traditional universities,
• a company’s development plan, or
• family (especially parents) advice.

In this article, I’ll show you how you can analyze your career options and create a well-informed plan.

Note! I mean this as an exercise that will take a few hours of thinking about your career, and making real notes that you can review later.

List your long-term options

The first step will be to write a list of options you are considering. Someone entering the tech industry could consider technical jobs such as:

• programming—a common end goal of the transition to IT,
• quality assurance (testing), or
• data science.

Or you might be considering non-technical roles—as a stepping stone toward tech roles or a goal in itself:

• project or product management
• data visualization
• user experience (UX) design
• customer success specialist

As you can see, there are many options available, and many more I forgot about. Writing them down will help you keep them all in mind while analyzing your career steps.

The goal of writing this list is to make it explicit what possibilities you are considering and what possibilities you reject (and why). At the same time, the list will show what options you are not aware of. This will be very helpful later on when looking for external feedback on your plan.

Make a pros and cons list for your options

Once you know what options you are considering, let’s write down what you believe are their pros and cons. There are no good and bad answers here—the goal is to make it explicit what you believe waits for you on each path. You are planning to change your career for some reason, and having your reasoning stated explicitly will make it easy to catch any obvious mistakes or unrealistic expectations.

Get someone to validate your way of thinking

So, after making a list of options you're considering, and making a list of pros and cons for each of them, you are ready to get external help. What you wrote is a perfect launching pad for a very productive conversation with the right person—you can show them a page or two that shows what you’re considering, and what you expect. With that, they will be able to point out any obvious mistakes in your understanding of the career you’re thinking about, or options you could consider as well.

The perfect person would be someone working in the industry you are interested in, someone who is on one of the paths you consider—but a few years ahead of you. You want an insider’s knowledge, but you need to keep in mind that people will know primarily how it was back in their days.

What I described is career mentoring, and many experienced people do it as a pay-it-forward thing, or just for fun. Maybe you already have someone who could help you in your network—try asking around. Alternatively, you can try online platforms to find free mentoring, such as coadingcoach, or look for some paid help.

Write a plan

After getting feedback on your expectations, you should have much more clarity about which direction makes the most sense in your situation. This brings us to another writing exercise: creating a plan of action to achieve your goal. It could be something a simple as:

To become junior JavaScript developer, I’ll:

• learn git,
• follow X course on my framework of choice,
• make an example application with … features, unit tests, continues integration, etc.

Or,

To become testing specialist, I’ll

• follow a Y course on manual testing,
• learn Cypress from Z resource,
• list 5 companies I would like to apply to

The plan description doesn't have to be long, but it would be good to make it precise—including links to resources you want to learn from. This will make it easier to evaluate.

Evaluate your plan

When you are done with your plan, you are ready to have another productive talk with your mentor. Again, having a document makes it effortless to get up to speed on a lot of information on a complicated topic in a very short time. Half a page plus a few links to courses or books will be enough to cover a half a year of your career development. With this information, it will be easy for your mentor to catch some obvious mistakes. For example, forgetting about Git if you want to become a programmer, or including some tools that you are very unlikely to use together—like Cypress and Playwright for end-to-end testing.

Execute

Having a good plan is just preparation—now you have to follow through with it. Good mentoring should address your second-guessing of decisions. Your mentor should provide you with enough context for their recommendation that you have clarity on why you do what you do.

Not doubting your plans fixes some source of delays, but not all. In any project, you can expect two things:

• to underestimate the difficulty of the challenge
• to overestimate time you can dedicate to it

It’s normal to have a 1-month plan take a few months—especially if you plan to do it on top of a full-time job, keeping up with other responsibilities and a healthy sleep schedule.

Free mentoring

If you are interested in analyzing your work plans with me, you can check the free mentoring page at my blog.

What is job hopping?

Job hopping is the practice of changing your workplace as often as possible, without looking suspicious on your CV. So, you get a job, learn technologies that the company uses and the internal process and the product they build, and then you start searching for a new job.

Advantages for employees

Job hopping is often recommended to devs as a way of making sure your compensation is up to the market rate. When you look for a job, you’ll naturally pay a lot of attention to the job market. If you are lucky, you’ll get offers from different companies and make them pitch against each other.

Another advantage is expanding your professional network: when you change companies, or even teams, you can meet new people who work in the industry. If they have a good experience working with you, they can be a valuable connection later on in your career.

Value of a long tenure

Staying a long time working on the same project is more productive. It can take a few months to get onboarded on a new project, and during this time you need a lot of oversight—or you make a lot of mistakes. Staying long term is an especially good match for companies that maintain and develop their own products. The projects are never ending, and they always need someone around to make sure the necessary changes can be made to the code.

Similarly, even companies that deal with shorter projects benefit from developers staying a long time. With time, you get experience with the technology stack that the company uses, and you can be very productive when some of the projects you built are reopened for updates or maintenance.

Institutional knowledge

By staying at the same company, you contribute to its institutional knowledge. You remember the past discussions and reasoning behind all the decisions that shaped the current state of the code and the infrastructure. The same goes for the emergencies and the fixes. Something that would take hours for a new person can be just fifteen minutes for you if you remember similar problems from the past.

Deep understanding

In time, you develop a better understanding of everything related to your job. You understand the product and how it’s helping the customers. Maybe you met some customer and over the course of that relationship you developed a better picture of the users of the application. You get to know the terminology of the industry in which the product is working, and there is less that has to be explained to you as you start building new features.

Knowing the code

After 8 years in one place, I have an advantage over any other developer: I know a lot about our codebase because I wrote a big part of it. In our repository, I’m an author of more than half of the commits, and at least half of the rest went through a thorough review with me. This knowledge is something specific to the project I work on—were I to change jobs, neither me nor my employer will get any use from it.

Sharing value of long tenure fairly

So, we have seen the advantages of job hopping for the employees and the value the long tenure has for the companies. Creating a lot of value for the company could be a common goal for both parties—after all, if the pie becomes bigger, there should be more for everybody. To make it work in the long term, both parties need to find a way to share this value fairly so that the employee will not leave.

Salary negotiation

Job hopping feels a bit like a workaround for lack of well-prepared salary negotiation. From the employee perspective, negotiating your salary is stressful:

• plenty of things depend on it
• it can feel closely related to your self-esteem (am I worth the salary I’m asking for?)
• at best, we do it every few years

At the same time, for the company representatives:

• they do it often: every time when somebody asks for a raise or applies to the company
• the stakes are low—it’s not personal and in most cases they don’t spend their money
• they know the market well—they know how much people at the company make, and what salaries new people ask for or accepts

This means that you need to prepare well. My go-to recommendation for that are resources from fearless salary negotiation. It’s a good, actionable guide that helped me a lot.

Baseline salary

The company you work for knows exactly how much you earn—or for how little you accepted working for them. But there is no reason for your new salary to stay within some relation to your current salary—especially if you were severely underpaid for a long time. Getting a 50% pay raise is not generous, if after it you are still below the market.

The only reasonable baseline salary is how much people with your experience are paid on the market. You will need to do some basic research to make sure your information is up-to-date: what is paid now for your current skill set. You most likely learned something new since you started your job, and the market changed as well.

Best alternatives

While preparing for the negotiations, it’s good to analyze the best alternative to a negotiated agreement for both you and your employer. For company, not reaching a deal with you can mean:

• having to find someone new for the market value and without your company-specific experience
• spending months on searching and onboarding a new employee
• if they use a recruitment firm, they will have to pay the fee for people they hire—it can be a few months worth of the new person’s salary

For you, the alternative can be as easy as getting back to the original idea of looking for a new job. In that case, you already have some market research done, and you have your negotiation skills refreshed.

Reduced hours

Another possibility to find a common ground with your employer is to negotiate working fewer hours, for the same pay. When you ask for a significantly better salary, you will very likely get either a straight no, or some version of “we would love to pay you better, but we have no budget for it”. Working fewer hours is a perfect solution for getting a better rate for you, and not affecting the company budget too much. Because you already know the project well, in the short to mid term, you will always be more productive than a possible replacement that would join for full time. And based on my experience, freeing a few hours or a whole day every week makes more of a difference to the quality of life than money.

When to leave company

We’ve spent a lot of time thinking about how to stay with the same company. Not all companies are worth the effort. Let’s see a few good reasons to leave:

• bad atmosphere—company that not only takes your time and energy but hurts your mental health as well
• inflexible negotiation—company willing to keep all the surplus of your experience for itself, while using guilt or loyalty to trick you into work for less than fair compensation
• getting a much better offer in another place, especially from companies with stronger foundations

Let’s get in touch

Salary negotiation is one of the topics I often discuss at my free mentoring sessions. If you are interested in analyzing your case, you can check out the mentoring page on my website.

• has conditions that cause a high turnover of employees, and
• developers don’t recommend as a workplace to their friends.

In short—companies that people leave as soon as they can. Let’s take a look at what you can expect at some of the jobs that are always hiring.

Waterfall

Often, you can find yourself working on projects that are of a fixed scope and fixed price. There is a list of features that the company promises to deliver and the price the customer is paying. Basically, a waterfall project. As soon as there is some unexpected issue, both partners find themselves in a conflict: either price goes up, or scope goes down, or the IT company gives up part of its profit. Such a low-trust environment makes it difficult to build anything besides a small, simple project—no more than a few months of work for a team of just a few people.

On the bright side, you can quickly try and test many different approaches to projects. Languages, technologies, processes, you name it. If you pay attention to what works and what doesn’t, you can get a lot of experience in a short time.

Besides that, there are plenty of downsides. It can be very chaotic, with many projects underway at the same time, distracting you and your colleagues. It can be stressful because spending a bit more time (or being paid for overtime) can mean that the company delivers the project at a loss.

Everything is cheap

A cheap customer, with their cheap project, will look for some cheap IT service provider. Then the provider will look for some cheap developer to fit into the budget, deliver something that the client accepts and still makes a profit. As a newcomer to the industry, you are likely to accept below-average rates, so that you and a company like this are a “good” match.

To add to this sad image, often because of razor-thin margins, even your workstation can be cheap as well. You will still be expected to stay productive and deliver stuff, so you better learn how to optimize your workflow on a slow, old computer.

Low quality

So, we have rushed projects, done by inexperienced developers on slow computers. You can expect the output’s quality to match that of the input. With projects that are defined for a limited time, it’s very tempting to trade long-term health to speed things up. The things that are likely to suffer first:

• documentation
• testing
• code architecture
• maintainability

It can be especially frustrating if you care about your craft and want to learn how to build good, quality projects that will be able to have a long and healthy life.

A lot of pressure and little support

Another common issue: limited resources, and built-in conflict with the customer, makes it very likely to put pressure on a dev team. Unfortunately, more stress at work is likely to only make things worse: you will make more mistakes as well as waste time and effort. At the same time, an environment like this does not invite code reviews, pair programming, or even helping out your colleagues when they need it. So, you are probably going to get little to no support.

Light at the end of the tunnel

It sounds pretty grim, doesn’t it? Luckily, every month you spend at a company like this, you gain experience, and you get closer to being able to get another, better job. When I was starting my career, I thought there was a trade-off where you get better money, but with worse conditions—longer hours, more stress, etc. Fortunately, for me, the opposite was true: every time I changed work, it was better for both money and general work conditions. It makes sense: if a company has money, it’s better to keep employees productive by not stressing them out, and hiring enough people to keep the workload doable. So, even if your first job in programming isn’t great, you are likely on the way to finding something better. Good luck!

Still interested in IT?

If you are still interested in starting your programming career, you may find these articles interesting:

• How to do web programming on an old computer,
• How to get a pay raise in IT

Operating system: Linux

When I was starting in IT in the 2000s in Poland, the default operating system (OS) was Windows. It was working OK on the new machines, but after a few years and few system updates, most PCs were becoming painfully slow. I hated all the visual bells and whistles that were appearing in the interface with each new OS version: what’s the point of things looking nice if the system is painfully slow?

My solution was switching to Linux. Luckily, all the tools I needed (Apache, PHP, MySQL, Git) were created for Linux, so they were faster and easier to configure there too.

The distribution that worked for me the best was Lubuntu—a lightweight Ubuntu with a desktop interface optimized for older machines. It’s still regularly released, so I would check it out if you are struggling with the speed of your development machine.

Command line as an IDE

To do web development, you need a browser and a code editor. Code editors are often installed as a part of an integrated development environment (IDE). At my first job, I had a bad time trying to use a big, Java-based IDE called Eclipse on an old PC. It was so slow that I was easily distracted while the computer was processing. It was seriously affecting my productivity, so I started searching for faster alternatives.

Part of my job was done over SSH on remote servers, so I developed a workflow based on command line tools. The best part of the command line interface (CLI) is that the tools integrate well by default—you don’t need an IDE to integrate them for you.

Tmux

Tmux is a program that allows you to run multiple sessions of a terminal inside one window. With a bit of effort, you can easily create nested sessions, and a script to start it up for you. I found it so easy to work with that

• I kept using a CLI-based workflow even when I switched to a much faster machine,
• I don’t use a second screen: switching between application windows or CLI sessions is efficient enough with keyboard shortcuts to make another screen almost useless.

Vim

Vim is a great command line text editor. Because it’s developed with a keyboard only in mind, every feature is available as a keyboard shortcut. At first, it might give you a headache or two—you will probably have to search how to exit the files. When you invest time in learning it, you will find its interface very efficient. I’ve learned Vim by following about ¼ of the video course here and by occasionally searching for a solution to some problems.

NeoVim is a modern Vim reimplementation. It has a plugin that allows you to use syntax highlighting and suggestions integration from VS Code. The configuration can be tricky at times, but you have access to all the same tools as other code editors.

Git

Git is a key tool for development. The core program has a CLI only. There are some tools promising better user experience with a graphical user interface (GUI), but

• I was never convinced by those promises, and
• performance-wise, you will be the safest using CLI.

CLI tools

Most tools used in programming are developed first for the command line and later integrated into IDEs or get a dedicated GUI. This means that directly from the CLI you can access the same commands that you can from IDE — or sometimes even more commands. The only issue can be typing them in without making mistakes, but you can address this by defining aliases.

Low-cost screen sharing

I have never done this outside of experiments, but with SSH and Tmux, you can share a CLI session over the internet. It can be especially helpful if your internet connection isn’t stable enough to carry voice and screen sharing. You can find a how-to guide here.

Learn more

If you are working on a machine with a lower performance, the articles might also be interesting for you:

• The Hitchhiker’s Guide to the Command Line,
• How to run nested tmux session,
• How to create Tmux session with a script,
• Intro to the terminal: basic commands that will help you get started,
• Why do people use the command-line interface