DEV Community: Emphie

Programmers, beware! Designers attack!

Mateusz Zdrzałek — Wed, 31 May 2023 09:55:00 +0000

Obligatory (my editor made me add it) Disclaimer 😉
All scenarios presented in this article are intended purely for humorous purposes and reflect the personal opinions of the author. The intention is not to offend anyone or specifically target real situations or projects. Any resemblance to actual events or projects is purely coincidental.

Intro

Are you familiar with that feeling when you come across a design that immediately triggers a cascade of expletives in your mind, making you question every decision that brought you to that particular moment? No? Well, consider yourself fortunate. Certain design practices have the uncanny ability to evoke such reactions from front-end developers. Regrettably, encountering one of these design challenges in a project often implies a high likelihood of encountering more. In this article, we will delve into the realm of designs that pose significant obstacles during development. Brace yourself for an insightful journey into the world of frustrating design choices. Let's embark on this adventure together!

Diagonal lines

Let's dive into a common predicament that many web developers face, regardless of their experience level. CSS, known for its love affair with rectangles, tends to make life difficult when it comes to anything else. You can squeeze out some rounded corners if you're lucky, but anything beyond that requires delving into the realm of hacky solutions. And that's exactly what we're about to explore. Picture this: a well-intentioned designer decides to spice things up with a "dynamic" and "interesting" divider between different sections of a website.

There are numerous approaches to tackle this problem, but my personal preference would be to employ an SVG triangle, as demonstrated in the illustration below. Implementing this solution isn't overly complicated, but how should it behave when scaling the browser? This crucial consideration should be in every designer's mind when creating any application element. Should the triangle maintain a fixed height or scale down accordingly? How will it affect the elements positioned below it? These are the pivotal questions that must be addressed in the design notes if the designer chooses to incorporate this element.

Floating elements

I can’t count how many times I had to deal with this one. Picture this scenario: the designer sees a bit of empty space on the page and starts thinking: “How can I make it more interesting?”, after exactly 0.01 seconds he figures it out: “Let’s add some floaty stuff and make the devs hate me!”.

I hate them so much 🥲 Those things are impossible to make them responsive. Usually, I just implement them on desktops, pray that they work on all the desktop screen sizes and completely remove them on mobile and tablets.

Inconsistent components

Here is another scenario. Your team has dedicated an entire week to diligently implementing the sleek and modern form components meticulously crafted by your designer. As the next sprint kicks off, you eagerly await the designs for a new contact page, only to be greeted by a jarring sight. The designer, seemingly in a quest for uniqueness, has opted for completely different components on this particular page. Faced with this situation, you have two possible routes to take:

Take a break to cry in the toilet and implement a second set of components to confuse the rest of the devs working on the project
Try to persuade the designer to use the already implemented elements, fail at it and finally go with route no. 1

Untranslatable design

Here's another familiar scenario that frontend developers often encounter. Imagine you're working on a multilingual page, and everything seems to be going smoothly with the design in the English version. However, as soon as you delve into different languages, the trouble begins to rear its head. Take a glance at the design above: a visually appealing offset image positioned behind a text box. Yet, when you switch to a language with more condensed text, such as Chinese, or one with wider text, like German, things start to appear a bit off.

So, how can we address this issue effectively? Well, the key here is open communication and collaboration with the designer. It's essential to consult with them and discuss potential solutions. And here's the twist: we might just need to make those delightful language-specific adjustments. Oh, the joy of adding complexity and messiness to our code! Who needs streamlined and clean code anyway, when we can have a tangled web of exceptions? However, by actively collaborating with the designer, we can find the right balance between accommodating different languages and maintaining code cleanliness. Together, we can navigate these challenges and ensure that the design looks fantastic, regardless of the language used.

Ending notes

One of the fundamental aspects of working with designers is creating a collaborative environment and ensuring a seamless exchange of ideas and experiences. As a programmer involved in a project, it's crucial to actively participate in the design process. By providing thoughtful notes and explaining your reasoning behind them, you can save valuable time by avoiding the need for extensive revisions or complicated design implementations. It's important to acknowledge that as a developer, you may not always have the final say in design decisions. After all, applications are built for users, not for developers. Keeping this perspective in mind will help foster a user-centric approach and ensure the ultimate success of the project. Remember, effective collaboration and embracing the user's perspective are key ingredients for creating remarkable applications!

The example design used in this article is available here: Figma Design. Send it to all your designer friends to either teach them something or just have a laugh! Those are only some of the annoying elements to code. Are you interested in learning more? Let me know in the comments because believe me, I have a lot more of them…

5 topics you should touch on during the recruitment process

Maciej Płatek — Thu, 20 Apr 2023 09:46:53 +0000

The recruitment processes can be weary and after answering countless questions you only think about leaving the interview, but you should never lose an opportunity to ask your interlocutors some questions. Why? There are a couple of reasons. First of all, there are a lot of things you should know before you accept the job offer. Another reason is more practical, when you are asking questions you look less intimidated and more experienced and so why not score some more points?

It’s important, however, to keep in mind that you shouldn't ask technical questions to HR people and vice versa, which can lead to uncomfortable situations. If you want to address any technical doubts you can ask if you may rise them on the next step of the recruitment process or maybe the recruiter can get you in touch with someone who can answer them.

I don’t want to crush you with an overwhelming list of all possible questions, because it may bring only more confusion. I present to you which topics you should stick to during the conversation to finish it with the most possible amount of information that should be handy.

1. Work organization

If you think about work organization, probably the first thing that comes to your mind is how your typical work day will look like. And that's the correct approach because that defines how your life will be going. Ask about hours, is it typical nine to five? Are there any office hours? Or maybe the company is totally flexible and you only should stick to the meetings? After you get the answer you will be sure if such day's composition suits you. So we already covered the meeting topic and to be frank - meetings can be harsh. Ask how many meetings you are scheduled to attend in a week. Some people prefer fewer meetings and if you are not sure what your preferences are - trust me, you prefer fewer ;)

Usually, based on the job offer, you already know if it is a remote, stationary or hybrid position, but even so, you should ask about that. Sometimes companies interpret remote jobs as “2 times a week in an office” or hybrid as “1 time a month from any location”. So better be sure than sorry. If you are expected frequently in an office, ask for free parking, because that can be a really big struggle in cities.

At this point you should know where and how you will work, so your next concern is equipment. Will the company provide you with a brand-new Macbook Pro? Can you expect to expand your home office to 8 monitors? Are peripherals even an option? Or will you need to use your old PC with a keyboard that is a house for a family of spiders?

2. Responsibilities and technicalities

Technical people should have technical responsibilities, that is obvious. Or at least it should be…but it’s not always the case. That’s why you should always ask about your responsibilities - what you need to do from starting working on a task till you mark it as “Done”. Will you be responsible for one project? Maybe besides the project, you are expected to handle something extra? Be inquisitive about it, and stick to this topic until your curiosity is satisfied.

After you finish the cross-examination about responsibilities, ask more specific questions. What does the technology stack look like? Which version of the framework is currently used? Unless you like working with legacy code, that is a good sign if a company uses one of the latest versions.

Another good idea is to ask about some advanced subjects. Is there Continuous Integration/Continuous Delivery used? How big is the test coverage? Are you working in Test Driven Development? Such questions will get you some bonus points.

3. Team organization

After you get knowledge about your responsibilities, now is the time to ask about people who will be sharing them with you. Will you be working in a team? How big is the team? Do teams cooperate on the same product? What roles do people have in your team? It is really important to know that. Workflow varies significantly between a team of 5 programmers and a team of 3 programmers, QA and Product Manager.

The next step will be to ask about the methodology the team is working on. Is it Agile? Maybe Scrum? Waterfall? Or some in-house implementation of principles? Trust me it is more important than you can think. If the recruiter is avoiding the answer then you can assume that something is wrong with the team organization (or it's not for just one particular project!).

4. Your future

Your future should always be your concern, even if you are treating the company as a temporary stop. Courses, conferences, training, and certifications are the things that can positively affect your future and have a really good impact on your career. For junior developers such opportunities can be even more valuable than financial benefits. Ask if there is any budget for such activities.

On the other hand, consider asking about your career in the company. How often can you expect an evaluation meeting where you can ask about a pay raise? Can you get a promotion to higher positions? Don’t be afraid to ask that, it will not be considered rude, but rather appreciated that you are looking forward to developing and planning to build a career path.

5. Benefits and events

The last position on our list is focused on benefits and events. Benefits consider all kinds of bonuses you can expect from a company. For example, it can be private insurance, private healthcare, a lunch card or some kind of sports card. It varies between companies, some of them are giving you a lot of benefits, while others prefer giving you more on your paycheck.

Other things considered bonuses are company events. Such an event can be a typical activity that is helping build bonds with a team, so parties in restaurants, go-karts, bowling etc. Even if you are a hardcore introvert and you have no interest in them you should know what to expect. But social events are not the only activity you can expect a company to host. Ask about a hackathon or some kind of internal knowledge-sharing meeting.

Summary

Repeating “don’t be afraid to ask” can be a good summary of my pieces of advice list ;).

Treat recruitment meetings as a source of information, both for the recruiter and you. Before accepting a position be sure that there are no unknowns. This is especially important if you are in more than one recruitment process because you shouldn’t decide on an offer only salary-wise. Asking important questions should get you a brief understanding of how a company is doing and if it is the right place for you.

Good luck with your next job interview, I’m sure that you will make a good impression!

Monorepo - when to choose it for your project? 5 heuristics worth considering

Adrian Piętka — Thu, 09 Feb 2023 10:54:00 +0000

Only a few years ago, I kept everything that was connected to the project in one repository. But then dividing projects into smaller parts became the norm. It was a fascination with microservices - every service was put into a new repository.

This approach caused several problems like versioning and compatibility, duplication of the code, dependent implementations, and multiple coding standards, even though we kept all the repositories as one, etc...

Nowadays, more and more frequently, we go back to the monorepo pattern - only one repository. It’s not in pursuit of the trend, rather for me, it’s an additional technique that I can use when it will be useful.

Should we choose the monorepo pattern in a new (or already existing and under development) project? In this article, I will try to explain five heuristics worth using for discussion and decision-making.

But be careful!

Don’t instantly use this list with your team! My intention is to give you inspiration for preparing your own list. Then to develop it, transform it. In the end, various conditions can affect the decisions.

Usually, it’s not easy to answer the question “is monorepo suitable for my project?”.

With the below list, you’ll be a step ahead when you don’t know where to start.

Do I have technological consistency?

During the requirements analysis and architecture design phases we are able to see the boundaries between particular parts of the project very quickly. It can occur for various reasons eg.
different business context another scaling model a specific way of data processing

This is the moment to extract particular parts of the project and map them to applications with specific purposes. It’s also worth asking yourself a question at this moment...

Is it still going to be the same programming language?

If the answer to this question is yes, then we have technological compliance. It’s important information and if we have it, it’s worth keeping the applications together.

Going further, it’s worth asking another question...

Is it still going to be the same framework?

If the answer to this question is yes, then we have perfect technological compliance.

In this case, we will probably be using the same tools: CLI applications (supporting code generation), package manager, statistical analysis of the code tool, the code formatting tool, etc...

There is no need to introduce the same configurations or change them later for a few repositories. Let’s keep them together.

Do I share the code between applications?

Let me tell you a story. A project that I was a part of started struggling with sharing API interfaces. We wanted to be common and reflect the current API state.

In the beginning, we could have taken the submodule principle. The ones we know from Git. But it’s still a separate repository that you need to take care of. Many times someone forgot to introduce an appropriate fix after the changes in API... It simply didn’t work.

Later on, code fragments appeared that were so big they could have been external libraries. It’s still the same problem. We add a new function to the library and we need to update it everywhere to the newest version.

Some new Merge Requests, appropriate scaling order… Eh… Pain in the neck.

Private libraries, published and applied on the basis of external dependencies generated more general service than the value added from the function.

When I see code duplication between applications I usually want to extract it to the independent library. The idea is good but not without, often unforeseen, flaws. Cycling of versions, backward compatibility (because we don’t want to use a newer version yet), and bouncing up versions in applications that use the library. It’s quite a lot of things to take care of.

Monorepo gives a faster service for this kind of shared code. Especially if we are the only ones using it. An actual duplication shouldn’t be in a library that is used outside our project.

It’s just a reusable code in our system. Nowhere else.

Do I have a similar implementation model (CI/CD)?

In certain moments a few of our applications are implemented into a test or production environment.

Perhaps the implementation process is identical and for example, it may consist of the below steps (example strongly generalized) for all of our applications:
Build a Docker Image with an application
Publish an image in Docker Registry
Update service to the new version in Amazon ECS

When the implementation process matches between applications, then we have a good control point. We will be able to use automation scripts again, without the need for copying them between repositories.

One Jenkins Job was able to implement every application from a big system. A joint process for all of the applications was prepared. Thanks to that, when a change in the process appeared (eg. adding a notification on Slack) then it was immediately used in every implementation.

Do I need to sustain compatibility between applications?

Sustaining compatibility between communicating applications (with API, and queues) is not an easy challenge. When a new structure of data appears or the existing one changes, there is a need for adequate preparation - eg. supporting new and old structures in a temporary manner.

The matter may be even more complex when the structure isn’t dependent on us and it needs to be suited to a cycle.

Implementation of the all necessary changes between projects at the same time becomes easier. For example, adding one necessary box. We can deliver everything at the same time and be certain that the actual state of the code as it allows us to use the change in all of the applications.

Is there only one application development team?

I worked for the teams that were sustaining polyrepo for the project. Every microservice had its own repository.

Maintaining attention with constant changes being introduced by the team was exhausting. I had seven repositories that I needed to watch. I was constantly looking for changes, updating each of them, rebuilding the application, or installing new packs…

Not to mention introducing new people to repositories. I can remember the look on their faces when there was a need of installing seven different applications so that the project can operate in its entirety. Sometimes there was no need to do that but as a team, we each looked after all of the applications, so in the end everyone could program everywhere else.

In monorepo it’s easier to organize the automation of that kind of process. Installing the project, starting it, or updating it after the implemented changes, go much smoother. Especially when we use the tools supporting working with monorepo eg. rush.

Monorepo - is it a good idea?

Remember that every project, team, or business expectation affects decision-making. If after a few months of work, we start to feel uncomfortable working with monorepo / polyrepo then it's worth having retrospective thoughts and thinking of improvements.

These problems can always be solved differently. It can occur that CI/CD implementation looks a little different, but it’s still worth putting the application in with the rest in monorepo.

Sometimes creating suitable scripts or doing an additional pipeline in CI/CD is all that it takes. And sometimes we are gonna be forced to change our approach.

My propositions are not set in stone. They are points to be discussed. Their main goal is to encourage team talks about it.

And what do you put attention to? Do you have any control points?

Source of most problems in projects? Miscommunication!

Michał Żurakowski — Wed, 16 Nov 2022 07:43:27 +0000

Poor choice of technology, Friday afternoon releases, infrastructure problems, package-dependent conflicts, legacy code... or as I call them – developers’ nightmares. There are many problems with the projects we’re working on. Surprisingly, the most common, is at the same time, the most obvious. Even Robert Plant from Led Zeppelin sang about it in one of his songs... yeah, I am referring to ‘Communication Breakdown’ ;) – an issue that is relevant even in the 21st century.

Open-secret

I have worked as a dev for over 6 years now and believe me, I have come across communication issues too many times, more than I would have liked. Let me share a few stories and some thoughts with you, it may help you look at it from a different perspective.

Ok, time for some ‘revealing’ insight – in my opinion, the source of most communication problems is the difference in people's characters. People are different and being on the same wavelength isn’t common. What one person perceives as a clear message, is often ambiguous and confusing to someone else.

Many times, when I was sure that I gave a detailed description of the problem, I later realized that my message was too complicated... and often too long! Similarly, I remember situations when I was given brief and vague information, resulting in a lot of time spent trying to understand someone else's riddle. After reading the text a few times, I still wasn’t sure if I understood all the information.

Keep it real clear!

Finding a balance and a happy medium is key. It’s important to avoid unnecessary details that are clouding your message. You should remember that simple requests like “set an environment” or “make a nice contact form” could not be enough. It could be fine when you have known and worked with someone for a long time and you have built a mutual understanding, but when you are texting someone you have known only for a few weeks, or with an inexperienced intern, the end result of your simple request, may be something quite unexpected...

I have noticed that dividing your message into sections and subsections can work miracles. It’s good to split your message with titles and headings, or with formatting features. Text editing tools are very useful for making the message more digestible to the reader.

Pro tip – read your message before you send it. I bet that in 9 out of 10 cases you will correct some typos or change some sentences. If you follow these rules you will avoid some serious f*ups.

Story time!

Let me tell you a story my friend shared with me. It is about communication issues leading to a monumental f*up. He worked for a small company with just one requirement – to use Git. Some time ago two juniors (but with some experience) were given a task to code a simple web page. Let’s be honest – it’s a week of work for an intermediate dev. And how did our heroes handle this project? Well, they met, divided the tasks, put the headphones on, and focused on themselves for five days. On Friday they reviewed their progress. It turned out they failed to implement a few critical elements. They both thought that the other person would be handling those specific things. It ended with them working all weekend to finish the project, only just before Monday’s deadline, with the whole office making fun of them. Both did not work there for too much longer.

Commas, in wrong, locations ;) and talking to people

What may appear to be foolish, but is not, is not paying attention to punctuation. Punctuation is very important! It’s crucial for text messaging. I mean - you don’t have to become the Stephen King of the company’s Slack, but it’s worth thinking about how many ways your message could be interpreted. For example, the sentence “install Visual Studio Code npm Angular Git Docker We will configure later” is not very clear. By using appropriate punctuation you will make sentences readable, as per the author’s intention.

It’s the same with spoken language. Ambiguity can lead to miscommunication, but more than that, it has the potential to affect working relationships if done without due care. In face-to-face meetings, it is often a necessity to adapt to others. Of course, you could scold an intern for not making a backup, but you should ask yourself a question, what would you achieve with that? You will most certainly ruin your relationship and jeopardize the chances for successful future cooperation.

Time for my second piece of clichéd advice - treat others the same way you would like to be treated. As I mentioned earlier, people are different, and it’s worth keeping that in mind. Some enjoy it when Jean Michel Jarre tickles their eardrums with his music. Others love the gentle sounds of Napalm Death. Some get annoyed with people invading their personal space, while others are driven mad by people who avoid them. It’s worth being aware of others’ differences and developing empathy within ourselves. I’m not talking about pretending to be someone you’re not. What I mean is to respect and understand others to make sure they feel comfortable around you. And that is the key to successful communication.

A few words at the end from... an introvert

This text is from the perspective of a guy who has problems expressing his thoughts. But the things I highlighted above are helping me improve my communication. I feel that being aware of your weak points is the first step to improvement. The next step is learning from your mistakes and then practicing to avoid repeating them.

So don’t give up, even after f*ups. You’ll get better with every message and meeting!

f*ups that made me a better programmer

Michał Hadamik — Thu, 29 Sep 2022 09:58:41 +0000

How about not spending your weekends on fixing bugs that could have been easily predicted and not rushing because you underestimated the time you will spend on a project?

Well, read about my f*ups guide to learn from my mistakes and avoid your own!

Do backups regularly

Let me tell you a story. In one of my previous jobs, I was the person responsible for making manual backups for WordPress websites. I did it every month, but one month I forgot! Guess what happened... Yeah, our website server was attacked, I didn’t think it would be significant as I made backups regularly. I thought I could just upload the last version I had, but after checking the folder on the NAS server and looking for copies, I nearly had a mini heart attack! It transpired that that month, there were a lot of changes to the website. As a result, I spend two weekends making the changes and cleaning the server. I never forget to backup now!

Pro tip – It is also good practice to make backups before making plugins and theme updates!

Double check the sandbox version with someone before releasing it

We have all been in a situation when a client asked for “a little amendment”? Something along the lines of “Please, make this change quickly in the live environment, it’s small and won’t affect anything”. It’s an accident waiting to happen! You agree because it’s a “small” change/fix and of course, you decide not to test in the sandbox because it’s 4pm on Friday and all you can think about is the weekend. What could possibly go wrong? Well… everything!

It happened to me a few times in my developer career, but the story I will remember forever happened on Christmas Eve… The client had asked to introduce some changes to a WordPress-based website. It wasn’t complicated but there were a few changes and very little time to implement. I still remember applying changes late in the evening when all of the guys from my team were already sipping drinks at the work’s Christmas party. I was trying to fix one tiny change that didn’t work, it became apparent that one of the elements had the ‘!important’ attribute added to its style. Of course, it was a great evening and a fantastic party (I DID NOT GET TO ENJOY).

But I learned an important lesson from this - when you are pushing some changes that are not tested in the sandbox they won’t usually work. Finding issues can be quick but fixing them can take a long time, that time it resulted in my weekend starting at 7pm instead of 4pm!

Now I always remember to check the fixes, changes, and features in sandbox before deploying them. It is important to ALWAYS do it, even if it’s a “small” change. It’s also good practice to check the changes with someone else.

Take your time with the estimate

At the beginning of my career, when I received a project to do an estimate, I usually rushed it because I didn't want to spend a lot of time on this and of course, I didn't check the details of each element in the project.

Time for the story number 3 ;)

I was working on finishing a website project for a client. The last part of the development was adding a blog section. Before I progressed with this piece of work, the PM asked for an estimate. Well... I didn’t analyse it properly nor did I ask any detailed questions. I just took a look at the designs and picked one in less than 2 minutes! During coding, it turned out that they were all supposed to have some extra features and be based on Google Analytics… long story short – a few questions and a couple of minutes spent on choosing the right design would have spared me a few hours of adapting the design to the website.

What did I learn from this? Always remember to take time to complete an estimation. Don’t ever think; “this page is very simple, just search box and a list of posts”, and instead ask the questions and pick a solution carefully. You will save yourself a lot of time in the long run!

Summary

I’ve shared with you a few of the f*ups I’ve made over the years. I made mistakes and I am sure I will make more in the future. It’s impossible to avoid them because programming is so dynamic and ever-changing. But it’s always better to learn from somebody else’s mistakes instead of your own ;)

Let me summarise, these tips will help you avoid mistakes in the future:

Remember to make regular backups
Let somebody else check your work in a sandbox before deploying to production
Don’t be in a rush to estimate the job, always research thoroughly
Don’t deploy a product to production at 4pm on Friday... It will be 7am on Monday before you know it ;)
If you don’t know something, do some proper research or ask your co-workers for advice.

Thanks for reading and I hope my f*ups help you avoid mistakes!

3 effective methods of learning new programming technologies (and tips on how to use them)

Dariusz Cichorski — Wed, 31 Aug 2022 08:13:19 +0000

Introduction

Software development is a profession that requires great flexibility in the ever-changing world of technology and programming languages. It doesn't matter if you're just at the beginning of your career or if you're already an experienced dev, you'll have to adapt and learn new things.

Here's a list of 3 effective methods of learning new technologies that you can use.

Method 1: Learn from video tutorials

Video tutorials are a great way of learning new things. You can easily find free ones on popular video-streaming websites that will be enough for most cases. If you're unsure what exactly you should learn on your path of, let's say, front-end mastery, you can search for Bootcamp-type video tutorials curated by professionals. That will help you develop new skills along some predefined path.

When starting learning from a video tutorial it's good to skim it before spending much time on it. There are many reasons the tutorial might not be suitable for you - it may not teach the things you're interested in or its style might not fit your preferences. If that's the case, don't waste your time on it and search for another one. The internet’s resources are endless, therefore it's worth learning how to pick the good ones.

The important thing to note is that just watching videos is not enough. You can spend hours binge-watching and learn nothing. That's because the human mind always tries to save energy whenever it's possible and loses focus easily. To take the most out of watching video tutorials, don't rush it. Take the time you need to process the knowledge. If the tutorial takes 1 hour, it doesn't mean you have to finish it just as quickly. No time pressure, it's not a race! You'll benefit more from a learning process divided into days than rushing through one take.

Usually, you're asked to code along to the video. That's a good idea in most cases, as it boosts learning straight away, but there are drawbacks to that! You are forced to constantly pause the video and it may lead to losing focus. If that's the case for you, I recommend fully focusing on only the part of the tutorial, as they are usually divided into shorter, 10-30min sections, and then after finishing it, trying to write the same code (or solve the same problem) as the teacher from memory. If you can't remember something, try googling it - this way you'll learn effectively and practice searching (which will quickly become beneficial). If you're unable to find the solution this way, rewind the video and get back to it.

Method 2: Learn from blog posts and written tutorials

Another effective method of learning is reading blog posts and written tutorials. There are tons of those all over the internet. You can find ones created by respected teachers or code enthusiasts.

Written tutorials are no different from videos when it comes to approaching the problem and building your knowledge, so they can be treated as an alternative. Naturally, everyone is different so it's down to personal preferences which method you will like more.

The good thing about reading tutorials is that you can easily search through them (CTRL + F), which comes in handy in many situations and reduces the time needed to find something. What's more, you don't have to rewrite the code, as you can copy the snippets straight away. It's not always a good thing, as rewriting something may help in understanding and remembering it, so it's up to you to decide and use it as you need.

The nature of online publications keeps them easy to create and maintain. That's great because if you're interested in some novelty technology, there's a big chance someone has already written something about it. This form of learning has an advantage over reading official documentation as it's more human-user-friendly and often written in the non-robotic language. Most of the time it's also covering real-world scenarios and it's easier to use that knowledge in your work.

Method 3: Learn from the official documentation

Another alternative for learning new technology is going through its official documentation. In contrast to written tutorials, official docs have a particular form, as they are written in the specialized, more robotic language, which often makes them sound uninteresting. This can often be a problem for beginner programmers and can lead to not fully understanding it, but there's another side of the coin - this reference book form makes it great if you're already familiar with the technology and looking for some specific detail.

The great advantage of docs over other types of materials is that it packs the most accurate answers to all potential questions in one place, which saves you time searching them in other places.

Nowadays, good technology docs should contain a "Getting Started" guide, which often gives you a huge boost in getting on board with it and quickly learning the basics. Many other materials (video and written tutorials included) are based on them - or even just paraphrasing them. Despite that, docs may not be the perfect place to start for beginner programmers as they often assume that you already know a lot of programming fundamentals. This makes them great as an additional source of knowledge to tutorials or if you're learning a programming language, textbooks.

The docs are perfect when you want to search for something specific. You often find yourself in a situation where you remember the function name and want to learn the details - that's when you should use the docs search tool and you will be quickly redirected to the right place. It's always easier than trying to find it in a 700-page book or several hours-long video tutorials.

Conclusion

Those are 3 of the methods I've used the most while learning new technologies during my programming journey. It is very important to learn what method fits your preferences and is the most effective for you.

It's worth mentioning that whatever method you use, it's crucial to practice everything on your own. Those methods are just boosters for the learning process, and they should always be considered support for practical training.

Which methods of learning do you find the most effective and what are your opinions on them? The comment section is yours!

5 things I wish I knew before starting serious development (a journey into code perfection)

Dariusz Cichorski — Thu, 23 Jun 2022 10:00:43 +0000

Writing code that does the job is easy. Writing a beautiful code that is worthy of being called clean could be more troublesome. There are many opinions about what a clean code is. Some say it should be elegant, nice and pleasant. Others say it should be easily readable. Whatever definition you find, you can notice that the idea is for the author to care about the code that's being created.

According to Uncle Bob, the ratio between reading and writing code is equal to 10:1. Because of this, it's important to make sure the code meets the principles mentioned in this article (and many, many more that are not mentioned). Writing quality code is harder and takes more time, but trust me, it's a good investment.

There are several rules that you can follow while writing code that will improve its quality and take you a step closer to clean code mastery.

Use names that represent your intentions

Names are a fundamental part of writing code. There are names of the functions, parameters, classes, files, and folders. Using the right name can be crucial. Look at it as a time investment - it takes some, but it saves more.

The name of the function or class should be an answer to every potential question - it should indicate why it exists, what it does and how it's meant to be used. If the name requires a comment it may be an indication it does not represent the intention.

You can notice it's not easy to understand what the meaning of the field (even with the comment as the description):

m: number; // solving time

The name m does not explain anything - it doesn't indicate what the actual purpose of the field, and even the comment isn't precise enough. The below example of the name is much better as it answers every potential question about it and does not require any additional explanation:

solvingTimeInMinutes: number;

The same goes for functions. What's the purpose of the function below?

function calculate(value: number) {
  return (5 / 9) * (value - 32);
}

It's quite difficult to say, even though it's just a one-liner function. That's because the name and the parameter are not self-explanatory. Here's the same function, but represented with a clear intention:

function fahrenheitToCelsius(fahrenheit: number) {
  return (5 / 9) * (fahrenheit - 32);
}

To learn more about good naming practices search for:

programming naming conventions

Avoid comments (until you really need them)

A good comment can be a lifesaver. An unclear one can be deceptive and cause confusion. Unnecessary comments should be avoided, as the clean code should be self-explanatory and should tell the story on its own.

Here's an exaple of a very bad comment:

// Always returns true
function returnFalse() {
  return false;
}

The function above does not do what the comment says. Just imagine using a wrongly commented function in some real-world scenario. The consequences could be bad, right?

Same goes for the below situation:

// Checks if player takes part in rating
if (player.contexts.includes(PlayerContext.RankPlayer) && player.isActive())

It's much better to restructure the code and use something like this:

if (player.takesPartInRating())

The instruction above is much cleaner than its previous version - it clearly explains its purpose without the need for a comment.

But there's more than this - having code that regurarly uses comments as a sort of documentation requires more resources to keep it updated. You not only have to work on the code, but you also have to work on the comments to make sure they represent the intention behind the code. You also have to remember to keep them updated!

Another example of poor practice is keeping the commented-out code in the repository. There's nothing worse than the code like this:

const player = this.service.getPlayer();
player.initializeSession();
// player.setSessionStartTime();
// player.setNewlyCreatedSession();

The other developers working on that code will think the commented-out part is an important one and it should be kept for some reason. This leads to keeping some old junk code in the codebase, which should be avoided. Instead of commenting on the code, it should be removed.

In most cases seeing a comment means the code could be better, but there are some exceptions. One of them is a TODO comment.

// @TODO: integrate with amazing-service once it's ready
function doSomethingAmazing(): void {
  (...)
}

TODO comments indicate tasks that should be done, but are impossible to do right now. It can be a reminder to remove old functions or an indication that some problem should be solved. Most of the IDEs have features that allow targeting TODO comments quickly - they should be regularly targeted and solved.

Another example of a valuable comment is the one that describes the decision behind the code. Sometimes we are forced to use some frameworks or browser-specific stuff - in that case, a comment can be a lifesaver and reduce the time needed to understand it.

// Fix for scroll position computations
// See https://github.com/swimlane/ngx-datatable/issues/669 for details
setTimeout(() => 
  this.doSomething();
}, 200);

It's important to get rid of any noise in the code, but also take advantage of the knowledge that some comments are valuable and can be helpful.

To learn more about good comments practices and how to write code without the need for comments search for:

programming comments best practices
programming self-documenting code

Keep your code formatted

You only get one chance to make a first impression. That's why you should really focus on the code formatting as it's the first thing everyone reading the code sees. It's an aspect that instantly makes a statement about code quality and its consistency. The code should always be perfectly formatted and it's every line polished.

It's important to specify the rules of formatting code in the project to keep it consistent. Each project is different so the rules may also be different, but once we decide on them, they should be respected. Many tools can help to automatically format the code according to the rules.

What do you think about the below code?

  function  doSomethingAmazing ()  : void
    {
const data = this.service.loadData();

  data.executeImportantLogic() ;

    if(data.somethingHappening)
{

data.executeMoreImportantLogic();
 }


this.service.saveData(data);

 }

The function above would compile without any problem, but is it even readable? It's formatted very poorly and it becomes impossible to understand. As you can see the indent level is not respected (or even specified), there are many unnecessary blank spaces and blank lines that make it impossible to effectively read it.

We can format the function above like this:

function doSomethingAmazing(): void {
  const data = this.service.loadData();
  data.executeImportantLogic();

  if (data.somethingHappening) {
    data.executeMoreImportantLogic();
  }

  this.service.saveData(data);
}

It's much better this way, right?

It's important to stick to the guidelines of the language we use while formatting the code. Each language or framework comes with its own formatting standards that should be known and respected. Respecting them is crucial as it helps new team members in writing their first code in the project. With every new custom formatting rule, it becomes more difficult for newcomers to quickly adapt to it (and also for older team members).

Creating code that works is not enough. To keep code clean we need to focus on its formatting, which will improve its quality.

To learn more about code formatting search for:

code formatting best practices
insert your technology coding style guide

Keep your functions short (and their purpose straight)

One of the main principles of creating functions should be to keep them short and simple. Functions should be easy to understand as they focus on one thing only. Honoring that rule will greatly reduce the time needed to understand it.

It should also operate on one level of abstraction to prevent mixing up less important technical details with crucial logic. The abstraction in this case means a metaphorical layer in which we create the functions. If we had a function that creates a list and increments it, it would operate on two levels of abstraction: first for creating the list, second for incrementing it.

Let's analyse the below function (but don't spend too much time on this):

function solveTask(solution: TaskSolution): void {
  const player = this.playerService.getPlayer();

  if (!player.gamingProfile) {
    this.profileService.createNewProfileForPlayer(player);

    this.playerService.startSession();

    if (this.settingsService.notificationsEnabled) {
      this.notificationService.notify('Player profile session started.');
    }
  }

  const solutions = this.trainingService.getTaskSolutions(player);

  if (!solutions.any(sol => sol.id === solution.id)) {
    this.trainingService.reportPlayerSolution(solution, player);

    if (this.settingsService.notificationsEnabled) {
      this.notificationService.notify('Task completed!');
    }

    const achievementReached = this.achievementService.reportSolutionEvent(solution, player);

    if (achievementReached && this.settingsService.notificationsEnabled) {
      this.notificationService.notify('Achievement unlocked!');
    }
  }
}

As you can see the function above is not too long, but it fails the important principles we've covered before. Firstly, it does more than one thing. Secondly, it does not operate on one abstraction level - it mixes different abstraction levels. Also, there's a code duplication there as the same code exists more than once. This function could be restructured by decomposing as per the below:

function solveTask(solution: TaskSolution): void {
  const player = this.playerService.getPlayer();
  this.handleGamingProfileCreation(player);
  this.handleReportingSolvedTask(player, solution);
}

Which would then use the functions below:

function handleGamingProfileCreation(player: Player): void {
  if (this.hasGamingProfile(player)) {
    return;                                                
  }

  this.createPlayerGamingProfile(player);
}

function handleReportingSolvedTask(player: Player, solution: TaskSolutin): void {
  if (this.alreadySolvedTask(player, solution)) {
    return;
  }

  this.reportSolvedTask(player, solution);
}

The functions handleGamingProfileCreation and handleTaskSolving have been decomposed from the original function.

This way solveTask function does one thing only - solves a task. It's operating on its abstraction level and it delegates its original logic into functions that are smaller, more focused, and easier to understand. Note that each function operates on a different abstraction level - one handles gaming profile creation and the other one handles reporting of the solved task.

The decomposing process we've covered may become very handy in restructuring (or creating) complex functions and can lead to a cleaner and better code.

It's worth mentioning that not all of the code should be decomposed into small functions. Some cases could lead to having 10 different functions that are used only in our decomposed function. It's a trap that should be avoided if possible. You should make decisions about decomposition based on the function readability. If you struggle with that, there are some questions worth asking that may be helpful in making the decision:

Will someone else make use of that function?
Can the decomposed function be public?
Will it help in creating unit tests?
Am I getting rid of complexity or adding it?

To learn more about creating quality functions search for:

programming functions good practices
programming functions abstractions
programming refactoring decomposition

Be a team player

The last (but not least) rule while working on the code quality is to be a team player. Most of the projects are developed by a multi-developer team. That's why it becomes crucial to cooperatively work on the code quality.

Being a team player is also treating the code as ours, not mine or theirs. Each team member is evenly responsible for its quality. There will be many cases in which you will encounter code blocks that were written in the past and require some treatment, e.g. badly named fields or wrongly formatted functions. In those cases the rule of leaving the code in a better shape than we saw it comes to life - it's not forbidden to improve code that someone else wrote earlier as we all work on the same codebase. The code will benefit greatly from respecting this rule, as its quality will always increase.

It's also important to remember, especially while doing code reviews, that we are reviewing someone else's code and not the actual person - this is a crucial part of keeping team spirit and respecting each other. This way of thinking about the code also helps in sharing code with others - as it decreases the fear of being offended by another project member. It also increases the discussions about the code itself, which is a key aspect of constantly increasing code quality.

Conclusion

A professional developer should always write the best code possible. It isn't easy, it's the process of constantly learning new aspects of improving things, but it's the way to go as it decreases many potential issues and increases overall quality.

Writing code is a work of art - it should be perfect, but perfect doesn't always mean the same.

Pair Programming: are two heads better than one?

Cezary Michalak — Wed, 27 Apr 2022 09:36:04 +0000

First things first - what is pair programming?

Pair programming is a development practice in which two programmers work together in one workspace. It allows developers to learn from each other and improve code quality through knowledge sharing and discussion.

When and why should we use it?

For the difficult or most important parts of the software
You are more likely to make mistakes or to miss something in the more complex tasks. The second person could help to improve the quality of the code, by looking from a different perspective, reviewing your code live, or discussing a problem.

When recruiting new employees
Pair programming can be a great tool in the recruitment process. It allows you to easily verify both the technical and soft skills of the potential employee. However, it is worth remembering that this method may generate more stress in the candidate, which may adversely affect the result.

For the introduction of a new person to the project
It always takes a little time to adapt to a new project. If a person that is already in it, shows you the code and explains it to you, it can really increase the speed at which you will get accustomed to methodologies used in the project and increase your understanding of it.

When training technical and soft skills
Not only is this a good method for less advanced programmers to learn from more advanced programmers, but also more advanced programmers can learn from each other through discussion.

Variations of programming in pairs

There are three options for working in pairs based on the experience of the people involved:

Newbie-newbie: Novice programmers can effectively resolve the hardest problems as a pair
Expert–newbie: Useful as a teaching method, because an expert can share their knowledge easily
Expert–expert: A good choice for creating very important parts of the software

The main techniques

There are quite a few types of pairings, some of which are:

Driver-navigator: The most popular technique. One developer (“driver”) writes code while the other (“navigator”) reviews each line of code, asks questions and thinks ahead
Backseat navigator: When we hit the wall while solving a problem, sometimes we don't see alternative ways. Then when someone looks at the problem from a different perspective, this canl be useful
Tour Guide: A good way to implement a new programmer to the project. A developer who was already in the project codes and explains how the application works whilst a new developer observes and asks questions
Ping-Pong: Perfect when we use Test-Driven Development (TDD) methodology, one programmer writes the tests while the other the code to be tested
Unstructured: This is total freestyle without any patterns. It is effective if the developers trust each other

Advantages of pair programming

Here are some reasons why you should consider using this methodology:

Mistakes are usually detected immediately
Code is shorter and more qualitative
Problems are resolved faster
Developers learn from each other
Programmers train their soft skills
The whole team is more integrated
The individual parts of the application don’t depend on one developer, which makes absence problematic
It's easier to get to know the other developers

Is working in pairs free from disadvantages?

Like everything else, this kind of work also has its downsides:

Coding is slower while discussing
It can quickly becomes tiring
Conflicts between developers may occur
It can be difficult for introverted programmers
The coder may feel stressed by being watched all the time
The navigator may be reluctant to give feedback to the driver
In stationary pair programming, problems may be caused by the difference in chair height, screen brightness, mouse, keyboard, or IDE
It takes some time and practice to get used to it

Remote pair programming

These days we work remotely more often, but this is not an obstacle to working in pairs unless programmers work asynchronously.

Visual Studio Code has an awesome tool called “Live Share” which is Made by Microsoft. It allows you not only to see what another programmer is coding, but also we can code with them, talk, and share the terminals and ports. It makes work more comfortable and easier to get started.

What rules should be followed?

For pair programming to work, the following rules must be followed:

Swap roles: Don't occupy the keyboard all the time, let your co-worker prove themselves
Be nice: It's easier to work together in a relaxed atmosphere
Use a familiar environment: Communication will be easier when both of you are comfortable
Ask questions: Don't be afraid to ask questions
Take a break: Take a 5-minute break every hour or when you need to
Trust each other: Don't criticize in advance, be patient
Control your ego: Your partner doesn’t criticize you, but your code, so listen to them and if you disagree, have a discussion
Say I'm sorry: Sometimes we get carried away, or we unknowingly hurt someone, be mindful
Don't be skeptical: If you have a negative approach, you will fail
Think about your differences as something good: Don't take the difference in another person's thinking as a disadvantage, but as an advantage
Watch the time: Long sessions lose their effectiveness and can tire you out. Sessions should last between 2 to 2.5 hours
Change your partner: It is worth getting to know the skill sets of new people so you can learn from them
Remember - you are a team: Everything you produce is a joint effort

So should I start my adventure with pair programming?

Well, it depends. Each case is different and the methods should be adapted to the problem, never the other way around.

If you think this might work for your situation, you should consider trying it out!

A quest to find TypeScript's inheritance tree (with top and bottom types as main NPCs)

Dariusz Cichorski — Thu, 07 Apr 2022 11:00:02 +0000

Introduction

I need you to imagine that you’re a lvl 5 software developer aka. computer mage trying to level up fast. What’s the quickest way to do that? By doing NPC’s quests!

And today’s mission is to find TypeScript's inheritance tree. You constantly need to get some experience to develop your skills.

Object-oriented programming is a way of reflecting anything with the usage of objects with specific behaviors. As in life, those objects can share certain similarities - that's where inheritance comes in.

It's a very important aspect of programming, as it is one of the key factors that impact the code quality, especially in highly scalable systems.

TypeScript, as an example of object-oriented programming language, also supports inheritance, but it comes with some specifics worth knowing.

Join me in a quest of finding TypeScript's inheritance tree and learning about the associated top and bottom types. And trust me, such a quest can become a real journey with highs and lows on our way (literally).

Quest started - Difficulty level: MEDIUM

Finding class inheritance tree

To start, let's get straight to the point and create our first class: a Hero:

class Hero {
  private name: string;

  constructor (name: string) {
    this.name = name;
  }
}

With that sorted out, let's go further and create two other classes which will extend the Hero class:

class Jedi extends Hero {
  constructor() {
    super('Luke Skywalker')
  }
}

class BountyHunter extends Hero {
  constructor() {
    super('Bossk')
  }
}

The above code is a perfect example of how inheritance works in TypeScript. By extending the base class Hero, we've created two other classes: Jedi and BountyHunter, which now share all of the Hero's attributes (in our case: a name).

We can therefore say that:

A Jedi is a child class and the Hero is the parent class.

A BountyHunter is a child class and the Hero is the parent class.

If you think about it, we've just created a simple inheritance tree, which in our case looks like this:

The class inheritance tree is a reflection of how different classes extend each other and what the relationships are between them. Every type in TypeScript is part of the inheritance tree.

The tree always has multiple levels - like the one above has two (one with Hero, the second one with Jedi and BountyHunter).

Looking at the inheritance tree we can see how specific the types are on certain levels. In our case, the Hero class is the least specific type because it's above the others. Jedi and BountyHunter are more specific extensions of the Hero type.

Climbing up the inheritance tree

What if I told you there's more than that at the top of our tree? Right now the tree looks more like this:

In TypeScript every type inherits from the Object type, which means that our Hero class is the extension of that type, too. This type comes with some familiar methods that we can use, e.g. toString(), hasOwnProperty().

What's interesting in the tree is that when you look closely, you will notice the String class is another type extending the Object and it's at the same level as our Hero! There are in fact more types on this level - including all of the classes we create.

But the Object isn't our final destination. At the very top of our tree is the Unknown type - it's the least specific type in TypeScript's inheritance mechanism. You're probably wondering what's the purpose of this type, as it is in fact completely empty, without any properties and methods. Let me explain, as this is a very useful one.

Into the unknown

I'm sure you've had thousands of situations in which it was hard to specify what the exact type of the value was. It happens a lot when you work with some external APIs or libraries. I've seen the type Any being used many times in such scenarios. But that's actually a big antipattern and potential danger for our code. Unknown type requires some additional handling but it also decreases the potential for bugs thanks to the help of a compiler.

It's worth noting that a lot of the time, a programmer is responsible for using the Unknown type. It's a clear indication that the type you're dealing with should be double checked before using. And such indication comes with a lot of support from the compiler, as you'll learn in the cases below.

Type guards

The cases in which there is no guarantee what the value is, are a perfect opportunity to use the Unknown type. It makes sure that those values are not used without being strictly checked. To do so we can implement type guards:

function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isHero(maybeHero: unknown): maybeHero is Hero {
  return maybeHero instanceof Hero;
}

Using such functions makes us secure about the type of the value. As you can see it is a very easy way of checking if the unknown value is some simple type (e.g. string) or some complex class (e.g. Hero). What's more is that once you use such a function, the compiler will know the type of checked value:

const something: unknown = 'something';

if (!isString(something)) {
  // something is of type unknown here
  throw new Error('Unsupported type.')
}

console.log(something); // something is of type string here

Type assertions

You can use type assertions while working with Unknown type:

function func(value: unknown) {
  (value as number).toFixed(2);
}

Such an assertion tells the compiler the type of the value, so it becomes possible to use type specific methods (e.g. toFixed() for a number). But at this point, as the NPC would say, "BEWARE! This way you are responsible for the type, not the compiler!"

Equality

In cases where you want to execute some logic when the Unknown type equals some specific value, you can do as follows:

function doSomethingAmazing(value: unknown) {
  if (value === 123) {
    amazeMe(value); // value is of type number
  }
}

What's interesting here is that the compiler knows exactly what the type of the value is if it passes the above conditional expression. So if the value equals 123, it means the value is a number! If a string (or any other type) is passed to the above function, it will execute without any error, but the conditional result will not be positive.

Falling down from the tree

We've already reached the top of the inheritance tree, but there's some unexplored area at the bottom of it. From that perspective it looks like this:

The Never type is the bottom of the inheritence tree. It inherits from every other type in the tree. Thanks to that nothing else is assignable to it. It's more specific than any other type so it can be assigned to everything else. There are some specific cases in which this type may be helpful.

Exhaustive checking

The most common use for the Never type is to achieve exhaustive checking in conditionals:

const heroOrHunter: Jedi | BountyHunter = new Jedi();

if (heroOrHunter instanceof Jedi) {
  console.log('I am a Jedi');
} else if (heroOrHunter instanceof BountyHunter) {
  console.log('I am a BountyHunter');
} else {
  const exhaustiveCheck: never = heroOrHunter;
  throw new Error(`Unknown type ${exhaustiveCheck}`);
}

The above code checks the type of heroOrHunter and executes some conditional logic. But in case there will be some other type in it, it will mark the type as Never, to make sure the compiler will stand strong against any other specific usage of that value. It can be very helpful and provide a higher level of code safety in more complex cases.

Error throwing function

Another common use of the Never type is as the return type of a function that exists only to throw an error:

function throwError(message: string): never {
  throw new Error(message);
}

This way we can prevent someone from using the value returned from this function as it now returns the Never type - which is the bottom type, so it cannot be assigned to anything. This makes it a reasonable alternative for returning Void.

In TypeScript a function that does not return a value returns undefined. Returning the Never type instead of Void produces a compiler error and prevents us from such a scenario:

function sayHi(): void {
  console.log('Hi');
}

const hi: void = sayHi();
console.log(speech); // Outputs: undefined

Conclusion and gaining EXP

We've explored TypeScript's inheritance tree and in doing so, we've covered the top and bottom types. That knowledge is one of the milestones of TypeScript's mastery.

Writing code that compiles successfully is one thing, the other is writing the code that is effective and bug-free. Using the knowledge we've learned during our quest will surely make it so.

Our quest is now complete and you, dear reader, are reaching the next level of your technical skills.

+1500 EXP!

Congrats! You are now lvl 6 software developer/computer mage.

Your next Quest awaits...

A ‘wise’ guy tactic for effective code review practice? Use checklist templates!

Maciej Płatek — Tue, 05 Apr 2022 08:13:08 +0000

I think everybody agrees on how important and useful practicing code review is. It helps you catch bugs early in the process and reduces long-term development time. It also has the benefits of sharing knowledge, improving estimation skills, and keeping the code consistent with established conventions within the project. In one sentence - it improves the overall quality of code. But how do you do it like the 'wise guy' from this article's title? The answer is simple.

Sometimes being a developer is all about trying to be structured - simply following rules and using the right tools. I know that performing Code Review (CR) can be a problem for some devs. To avoid all the traps and make the whole process easy and effective I recommend using checklists. They should be the first choice when you're performing semi repetitive tasks. So what's the argument against using them as templates? Yea, I don't know any either.

Basic rules - keep the lists short
The principal rule is to keep it simple. Lists that are too long are overwhelming and can backfire. Stick to the fundamentals and focus on the most important parts, however, it is meant to be useful so don’t hesitate to fit it to your needs. Rules should be listed in a specific order, because in most cases if one of the points is not fulfilled you should stop reviewing and contact the author. Of course, a checklist is beneficial not only for the reviewer, but the author of the code should be able to use it before submitting PR to remove obvious mistakes.

Automated tools are the key
Any automated tools that are used in a project must succeed. If any static program analysis or automated test reports a problem it has to be fixed before review. Automats are the first obstacle you need to overcome to start CR.

Are changes ready to be merged?
If PR has conflicts with the target branch there is no point in checking the code because you will probably need to perform a review one more time. This should be obvious, but often changes that are merged earlier can lead to new conflicts, and resolving them is the responsibility of the PR author.

Are commits messages correct?
Before you take a look at the code, check the commits messages. Comments like “Minor fix” or “Added new feature” are meaningless. Developers must stick to the commit convention used in the project, with no excuses.

Is PR small enough?

Neither you nor me have Chuck Norris' skills. Our perception is limited, so if PR consists of 3000 changed lines, you will have problems understanding changes. Remember to keep it small, but without forcing strict limits, because it needs to be flexible. If you have worries that your PR is too big, it probably is, so just check out the new children’s branch.

Are requirements met?
Requirements are the reason why the feature branch exists, so always check if changes fulfil them. Believe me - you don't want to spend time reviewing the whole code if requirements are not met. Been there, done that. Don't recommend it. Check ticket description, look if something is missing or is incorrectly implemented, and immediately report to the author if there is a problem.

Do you understand the code?
The question may seem odd, but it's important. To perform CR you must understand the code and be able to do it in a reasonable time. So code should be self-explanatory. If some functions don’t make sense or classes look messy, the code probably needs to be reorganized. You may be the next developer working on this part of the code, so take into account that this code will be merged to the main branch after your acceptance. Clicking the merge button or accepting the code review means you are now sharing responsibility.

Dev's first commandment - stick to the coding guide
I'll say it one more time - always stick to the coding guide. No excuses. Ever. Check if everything is correctly named, files have the correct structure and if the approach is consistent with principles, DRY, SOLID, or any other clean code rules team is using.

Do we need a library for that?
Libraries are a double-edged sword. Sometimes developers import huge and resource-consuming libraries and use only one function. It is only justified in cases when we can use more of it in future tasks. The second case is when developers add libraries that are similar to one already present in the project and duplicatesare never welcome. The last thing is to check is if the library is not maintained any longer or marked as deprecated

Duplication is not welcome
In most cases finding unnecessary duplications can be a part of the coding guidelines, but it is worth mentioning it as a separate point on the checklist. New team members in particular can have problems with creating duplications, so just point out which part of the code they should use. There is no need to reinvent the wheel, use language features and already existing functions instead of implementing similar features.

Test, test, test!
Yes, writing tests is also part of a task so check if they are correctly implemented and cover all coding paths. Just like normal code, tests should also meet coding guide standards and be consistent with project assumptions. Verify that all tests are passing for the right reason and take a second and think if there are any edge cases that haven’t been tested.

Documentation is a must
Right now you and the author of the code know what is going on. But will other team members be able to easily catch up and use or develop it? If you are reviewing API - check if all endpoints are correctly notated and documented. For frontend checks, you can confirm if everything is available at Storybook or another component explorer. Any libraries used or architecture solutions must be put into a decision log.

A ‘wise-guy’ conclusion ;)
This article provides you with several suggestions, but a good CR checklist must be agreed with the whole team. Keep in mind that checklists should be a live organisms, if you encounter problems in the development process just add new points or keep more than one type of CR template based on task type.

There you have it. Good luck with your next code review!

Code development guide: working with small chunks

Adrian Piętka — Fri, 18 Mar 2022 08:47:48 +0000

Final work with the code can be a real pain in the… neck. It is often a long and tedious process of going through and verifying all the changes which can bring you to a moment when frustration is directly proportional to the time spent on writing the code. Is there a way to tidy up the work and avoid those tears under the shower at the thought of another implementation? Yes, there is. You can work with small chunks.

What’s the prob, dev?

Imagine waking up after tens of minutes (or even hours!) of coding trance and seeing 50 changes in your editor. Changes were made in totally different places of the application.

You look at this code-battlefield and ask yourself *the same question the Ant-Man did. *“What the hell happened here?”... To make matters worse, not everything is working and you have a lot more to do because you poked your thumb in too many pies. Part of the changes has to be verified again and it will pull further changes. On top of that - you haven’t corrected even one test.

You know that means one thing - a need to go through and verify all the changes, remove the unwanted code, and fix the tests. Well, you could probably say that you’re starting iteration number 2. The problem is, you are tired and you lean towards leaving work for tomorrow. After all, you did a great job today. Isn’t it enough? ;)

Eventually, that approach drives me to the moment I don’t feel like working at all. It’s like complaining about other people’s work and making a much worse mess than the others. Frustrating, isn't it?

That’s why I try to organize my process of creating software by the little approach. Small, but thought through and effective steps.

Let me guide you through all the stages of the work and point out its important elements.

Let’s start with a good plan

Think over carefully how to approach the problem to finish the task as a whole. Focus only on your goal and only those changes that will lead you to achieving it.

What’s important - I rarely pay attention to the tasks I’ll be working on next week or in two weeks' time. I focus on it when the time is right. Not once and not twice I had prepared implementation for the future changes and finally, there was no need of doing all that work because requirements changed in the meantime. All the work that was done turned out to be a waste of time.

It’s hard because you’re often overwhelmed with tasks. You hear about SOLID, DRY, and the rest of the acronyms that make the whole thing messy and abstract. You end up wasting your time instead of just working on a specific piece of code.

This is the moment when you need to start making decisions. For instance, you need to decide if you’re implementing the strategy pattern or not. But on top of all that is if in the future you will be able to easily change/ replace the elements you are currently working on. Without deleting half of your code. I focus on coupling the changes with the rest of the code.

I tend to point out the work phases on a sticky note. After completing each task I can cross it out. But the real moment of little glory comes when all the tasks are completed and the crushed paper lands in the bin.

Of course, you can use the virtual sticky notes and have the satisfaction coming from clicking the delete button… but frankly, it’s just not the same ;)

The plan isn’t a carbon copy with the changes I’m implementing. It is because you can subdivide them into even smaller steps.

It is my high-level work plan and not the plan for the particular changes.

One change at a time

This is where it gets interesting. After preparing the plan it’s time for a serious fight - decomposing the work into smaller pieces.

Examination of borders and drawing a line where I start and finish the work is just a heuristic. In that matter, I rely on two factors.

A type of change is the first factor. I’ve defined a catalog of 5 different potential changes:

Change in the file and directory structure - changing names and moving them
Refactorization - preparing the ground in the accordance with Uncle Bob’s 'Clean Code' principle
Implementation - the most atomic and independent part of the function you’re working on
Fixing an error
Deleting an unnecessary, unused part of the code

I always try to make only one change at a time. The exception to this rule is when the changes are mutually exclusive, for example - changing the file name that fixes the error.

Unfortunately, there is a trap here because it’s impossible to describe decomposition in just five easy points.

Second factor. I verify if the change meets the assumptions below:

To be atomic
To be as independent of the future changes as possible. What I mean - it doesn’t require something that doesn’t exist yet
To be dependent on things I added earlier. What I mean - it can use previously added functions
To change one specific function
To apply only one specific file (ideal situation)
To easily describe the changes in just a few words (it makes creating commit messages a lot easier)
To start from the deepest changes, the ones at the end of the calls chain

Let me show you an example:

I add a function to calculate the X. It’s not used anywhere yet (new MathCalculations function)
I add a new endpoint that I’ll be taking actions in (only Controller action and route)
I add the validation of data coming to an endpoint
I add business logic (e.g. in UseCase)
I connect triggering logic with the endpoint

Theoretically and practically I am able to merge my changes with the main development branch. Nothing should happen because various elements are independent of the next steps I plan to take.

This is, of course, just an example and we may find that to point 4 we would need to add a new entity, repository, or generate a new table in the database. I would think about these as separate changes.

It’s important to remember that theoretically, one single change can require dividing it into many smaller pieces and each one of them follows exactly the same process. I was thinking about 3 changes… and I ended up making 7 :)

Decomposition is the key part here. Either you have it or the process itself won’t get you anywhere.

Earning the ability to do that won’t always mean it is going to be easy (but also no one promised it will be ;) ). You often need to know the system you’re modifying, its architecture, code structure, and the main principles it follows. Without them, working little by little is a lot more difficult. What’s important is that each new task is knowing the code and how the software was built. This is what makes us move around much quicker and with higher confidence.

In this step, I’m not afraid to use comments // @ TODO. But only to make my work in the next step easier and finally to replace it with an appropriate implementation.

Everything needs to work

Everything needs to work after the changes you made. Every added, deleted line or modification can’t have any side effects, e.g. damaged automated tests, defective SCA, or malfunctioning software. Everything needs to be compiled correctly.
What’s the next step? To check if everything works. I verify not only the app but also everything needed to implement the next change in the environment.

I tell more about the changes testing approach in my 'Programmer, Test!' article. You’ll find a list of points worth remembering in the process of changes verification.

Write it down!

Preparing the storytelling about changes in the right words is the final step. Remember, you need to explain what you have done and why.

I add files to the Staging Area (git add)
I make the Git Commit and the created history I put into the Commit Message

This is where I can make the next step. Part of the work I consider done has been secured and I can safely take the next step in this case

What Have I achieved?

First of all, using only one tool (git) I can track/monitor the progress of my work. Even if I had a difficult weekend due to my friend’s bachelor party I could still easily remember what I had done on Friday. And after getting rid of the hangover I am able to quickly get back to work on Monday morning… ;)

And what’s important - I can easily undo my experiments. All I need to do is to get back to a specific commit.

In my opinion, it’s important to take care of proper history creation used in Commit Message. You get this feeling of sweet harmony in your work. You know what you changed and most importantly why you had done it.

But on the other hand, if you don’t care about this you can use Git Squash to simply merge a few commits in one. That way you will describe the final result, not how you achieved it.

Obviously, as always, the right approach depends on the project you’re working on or simply your preferences.

Do I push every commit created?

It depends. Sometimes you co-work with someone on the same branch and your partner is waiting for your changes. The other time you will just upload them from time to time.

Over time you will get this on your list of habits and you will realize that the work is getting done faster. Next thing you know you have a bunch of tasks marked with the green ‘done’ tick. In the end - practice makes perfect, or rather “practice makes practitioner” ;)

In the end, I would like to draw your attention to 'Commit Often, Perfect Later, Publish Once: Git Best Practices'. Actually, I think this is where my adventure with the little by little work and Git approach had begun.

Can a man become a starship? Yes, in TypeScript. A guide to structural and nominal typing

Dariusz Cichorski — Wed, 09 Feb 2022 11:02:45 +0000

*TikTok music playing* You can do anything you want when you're... a programmer! But for real - programming has become a way of reflecting real-world, often providing a helping hand in various processes by using code. We can create all sorts of things.

Those things can have different shapes and meanings, serve different purposes and do all sorts of different stuff. Like making a man become a starship. Let's learn how to achieve that using TypeScript and, on the ocassion, gain some knowledge about structural and nominal typing.

TypeScript can be a good example of our starship-theorem because it's here for you when you need it. Nowadays, it's basically everywhere - both in front-end and back-end worlds, but to be precise and effective you have to remember some important things and use them to provide a valid solution to the problem.

Our assumption is as follows:

"A man cannot become a starship."

Sounds very simple and straightforward, right? Well, it's actually not so simple and I'll prove it to you.

Shaping the world

Let's play with our assumption in TypeScript. Let's say we have a man and a starship - they all have the same properties: name and id:

interface Person {
  name: string;
  id: number;
}

interface Starship {
  name: string;
  id: number;
}

Let's prepare some typical real-world situation:

const person: Person = {
  name: 'Han Solo',
  id: 1,
}

const starship: Starship = person;

Surprisingly, the code above is absolutely correct and will compile without any errors, but if you think about it, our assumption is broken. Why is that?

TypeScript (as the name suggests...) is built over types. If something has the exact same properties, it's the same thing. It doesn't matter that it's technically a different interface.

The difference comes when one of the interfaces is more specific than the other. Let's discuss the scenario as below:

interface Person {
  name: string;
  id: number;
}

interface Starship {
  name: string;
  id: number;
  serialNumber: string; // newly added field
}

This time, our real-world situation will behave a little differently:

const person: Person = {
  name: 'Han Solo',
  id: 1,
}

const starship: Starship = person; 
// Compiler error:
// Property serialNumber is missing in type 'Person' 
// but required in type 'Starship'.

Compiler error message pretty much sums that up, but why is that happening? By adding a new field serialNumber to the Starship interface it became a more specific type than the Person, which made it impossible assigning its value to the starship. Let's now change the rules and invert the real-world scenario:

const starship: Starship {
  name: 'Millenium Falcon',
  id: 1,
  serialNumber: 'YT 492727ZED'
}

const person: Person = starship;

The above scenario will compile successfully, because the starship contains all fields required in person type (name, id), so it can in fact become one.

To sum that up, it's safe to say that:

Types are considered the same if they share the same structure (fields).

More specific type can be assigned to the less specific type (but has to come with all required fields of the less specific type).

Less specific type cannot be assigned to the more specific type (as it does not come with all required fields).

What does that mean for our assumption? It means that a man can actually become a starship, but only when they share the same fields.

In TypeScript, all of that is called structural typing, which is the default type checking mechanism. It works well in most cases, but there are some that require more precision. In those cases, nominal typing comes to the rescue.

Being more serious

In situations when type integrity becomes a key aspect of our code, we have to dive a little deeper into what TypeScript is able to provide.

Nominal typing is a star in this case. Being able to relate objects strictly based on their types, not their members, it stands in contrast with structural typing.

Currently TypeScript has no native support for nominal types (see history of the topic), but there are a few ways we can easily implement it ourselves.

Branding

The first technique is called branding. It requires adding a brand field with a string literal as a value. Let's get back to our previous real-world situation, but this time, let's 'brand' our interfaces:

interface BrandedPerson {
  brand: 'person';
  name: string;
  id: number;
}

interface BrandedStarship {
  brand: 'starship';
  name: string;
  id: number;
}

const person = {
  name: 'Boba Fett',
  id: 1,
} as BrandedPerson;

const starship: BrandedStarship = person;
// Compiler error:
// Types of property 'brand' are incompatible.

The above code is pretty much the same that we implemented before using structural typing, but this time the compiler stands strong against letting a man become the starship, as they are in fact a different types.

As you probably already noticed, this technique comes with the disadvantage of requiring the implementation of additional fake object properties.

Enum Intersected Types

Another way of implementing nominal typing is using enums. In TypeScript enums are unique, so any type intersected with an enum becomes unique as well. Let's use that knowledge in our scenario:

enum PersonType {}
type Person = PersonType & {
  name: string;
  id: number;
}

enum StarshipType {}
type Starship = StarshipType & {
  name: string;
  id: number;
}

const person = {
  name: 'Boba Fett',
  id: 1,
} as Person;

const starship: Starship = person;
// Compiler error:
// Type ... is not assignable to type Starship.

As before, this serves our purpose of not letting a man become a starship, but this time using a type intersection with unique enum.

This technique comes with the advantage of not adding any fake properties (as in branding), but also with the disadvantage of returning two type declarations for every type.

Private Class Members

Yet another way of handling nominal typing is the usage of private class members that denote the types. As previously, let's look at the example below:

class Person {
  private person: void;
  name: string;
  id: number;
}

class Starship {
  private starship: void;
  name: string;
  id: number;
}

const person = {
  name: 'Boba Fett',
  id: 1,
} as Person;

const starship: Starship = person;
// Compiler error:
// Property 'starship' is missing in type 'Person'
// but required in type 'Starship'.

Given the compiler error we've got, this method also serves our purpose.

The concept of this is actually the same as branding, but if you look closely it comes with the advantage of not showing up additional property (brand) on the object, as it is private. Private class members can also be encapsulated.

Private Class Members Encapsulation

Let's be like Agent 47 for a moment with elegant and effective technique and play with some encapsulation. Here are our fundamentals:

class Tagged<T> { 
  private _secret_tag: T 
}

type Nominal<Type, Tag> = Type & Tagged<Tag>;

Having that prepared, let's get back to our previous scenario and code it using Nominal type:

type Person = Nominal<{
  name: string;
  id: number;
}, 'Person'>;

type Starship = Nominal<{
  name: string;
  id: number;
}, 'Starship'>;

const person = {
  name: 'Boba Fett',
  id: 1,
} as Person;

const starship: Starship = person;
// Compiler error:
// Type 'Person' is not assignable to type 'Starrship'.

Once again, the above implementation prevents a man from becoming a starship, which solves our issue.

The encapsulation gives us the power of hiding it in a utility file or utility library, which has a positive impact on our code quality. It also comes with the advantage of brand property not appearing on the object (like in previous techniques).

Motivation

Okay, we've come a long way since the start - we've learned about two different ways of type handling in TypeScript: structural and nominal typing and how to achieve them. But let's ask ourselves a question: is nominal typing really that important? It actually depends on the case.

Let's think about some system that requires encapsulation, e.g. encapsulation within modules - a scenario in which no code from the outside should interact with module code, except through explicit predefined channels.

In that case, nominal typing can be responsible for making sure that some predefined functions will not be called with simply any object that happens to have the same properties like the one that is required.

Nominal type makes a statement that the code using it is created specifically with this type in mind.

Let's go a little bit further with our encapsulation case and create a library that will play relaxing songs to keep us motivated in work for a certain amount of time. Instead of implementing it like that:

export function play<T>(time: number) {
  this.playSongsByBand('Slayer', time);
}

we can use nominal typing:

export type Minutes = Nominal<number, 'Minutes'>;

export function play<T>(time: Minutes) {
  this.playSongsByBand('Slayer', time);
}

As you can see, the above scenario benefits highly from using nominal typing. Instead of a function that takes an unspecified amount of time as a parameter, we end up with a self-explaining parameter in which you don't have to look to the documentation to understand its unit. And, as the type is nominal, you won't pass your age by mistake!

Conclusion

TypeScript mastery comes with understanding it. By knowing how it handles typing we can take our code to new heights.

Is nominal typing better than structural typing? No, the default typing mechanism will still be the one to go for most of the cases, but if you have a real need of being type sensitive, you know what you need to do.

We started with the starship-theorem. We did it not only because it gave me right to put here a cool transformers gif (or not only why) but also because it’s true. But to be true it must be as follows:

A man cannot become a starship. Unless you're using structural typing. Then in some cases it can...

A little bonus

Let's say we have a collection of different types that share the same property, e.g. name. We can implement a function that will take anything containing a name field and return its length.

function getNameLength(something: { name: string }) {
  return something.name.length;
}

This way, you can pass any type (e.g. Person, Starship, Company, Band, etc.) containing name field to this function.

This can be useful, right?