Engineering-Practices | karas.codes

Telling someone don't do it - considered harmful

Mon, 22 Jan 2024 00:00:00 +0000

Context

I heard a very interesting thing when being in the middle of yearly review call.

During a code review some unknown time ago I unfortunately asked someone (don’t know who) to not implement something in a specific way. What’s worse I did something similar in a code. Regrettably I don’t remember that, but probably I forgot explain my point. How dare I? What a hypocrite!

My mistake

I think my only mistake was not making 100% sure that the other person understand my point of view. I should state it very clearly, why they should not do a given thing with our codebase even though I did something similar in the past. My only excuse is I have always a lot in my plate (but I still try to help my colleagues), so probably I did not explain my point because I simply did not have enough time to do it properly.

The other side of the table

Why AFFECTED person did not ask me for details?

I truly try to understand that. Through my whole career, I have constantly asked questions to people who are more experienced than me because I want to understand things as deeply as possible.

This situation could have been resolved with one additional question.

Comments in the code review should not be perceived as orders

I am working at a company that has very flat structure. I feel like everybody in the team is equal.

Also, based on my experience with code review. My comments are only tips or advice to the person who wrote the code. When I am telling someone that they will shoot in their knee, they still can do it and I am ok with it.

But there is one exception

If you are changing the code that the other team maintains, you should follow instructions. Because maintainers always have more experience with it and knows what and when could be done or not. In addition, I think this is the case I wrote in the context section.

In other words, I won’t let you shoot in your knee if I will be asked to fix that later on…

Maintainers could do more than people that are clients of the code

Of course this is my opinion. If you are creator/maintainer of given code, then you could do with it some things that are restricted to the other teams.

Why?

Because (again) you know all internals of the code, know all edge cases, how this code performs etc.

Example

Let’s consider a feature flag module (it’s a very common module in SaaS applications, I think). It’s created by one team and exposed to the other teams inside a company. From my perspective feature flags should be used for technical things only - like things that our customers couldn’t see or manage. E.g.:

switching on or off given module in the app
changing internal configuration of given module
etc.

So if you spot a case, where someone is using this module as normal config of the given module (that could be changed by end users). What would you do? For sure, you will ask this person to not do that, but do in other way - I mean implement normal config managed by customer in this case.

Summary

I know I should explain my point of view more, but as I told sometimes you don’t have time for it. When you are maintaining code that is used by other teams.

Things that I should improve

Always write documentation that will describe all use cases in a clear way
Be more precise during code reviews
Ask more often if everything is understood

Please let me know if you have any other observations!

The Devil's Advocate Technique

Mon, 03 Apr 2023 00:00:00 +0000

This technique would be more useful for teams rather than freelancers. But I think anybody could take something valuable from using this technique.

Context

Imagine that you are working on some new module in your application, e.g. location module - that could be placed on both client or backend side. So we need to find out the best solution. You also have prepared a design for bot approaches - that takes maintainability, security, and performance into consideration.

The devil’s advocate technique

Once you have all things described above we could start doing a list of questions that you will get from e.g. CTO, Head of IT, team leads, or team members. You should also prepare another list of questions that you potentially receive from managers, marketing, and support teams.

Then you need to try to answer all of these questions to see your solution from different perspectives or angles.

You could also do a call with 1-2 team members that are more experienced than you, to receive questions you weren’t aware of. But don’t do it before preparing your list. Also preparing ADR before doing a call will save your teammates time.

Summary

This technique is very simple, and you don’t need to spend much more time implementing it. But you will produce way better solutions when you will be using it. Also, you will save time by spotting some potential problems or improvements even before starting the implementation stage.

If you will be following this approach for a long time, you will start becoming better and better at finding problems, improvements, or potential bugs that could occur, etc. This technique will also improve your creativity.

Hope you will find this post useful!

How Not to Get Stuck When Solving a Problem

Thu, 30 Mar 2023 00:00:00 +0000

Today I want to show you one approach that will let you spend less time-solving things.

Problem

For sure, you had a situation where you were stuck on solving some problems like implementing new features or worse trying to find a bug in your system. That happens every time then you’re doing interesting things and trying to learn something new. You are on a good path!

This is not a problem until you react to it in a good (for you) way :)

Bad approach - trying to solve a problem at any cost

I did that many times, like sitting in front of my desktop until I solve the problem. That approach is not the best because you are wasting your time. I mean, if you are tired, probably you won’t find out a brilliant solution. Also, finding, designing, or even implementing the correct solution would take more time. Instead of trying to solve that problem, you could e.g. solve some other task that is well-defined at the same time. That would give you a better outcome in the end.

But we all know that you must solve some complex problems and fix hard-to-debug issues. So…

Approach you should take

I will show you a couple of ideas that could improve your efficiency when you will stick to something:

Give yourself X amount of time e.g. 1h and do a short break after that. Making coffee, talking with your friend, or going for a short walk will let you reset your mind and think about other things. However, our subconscious will continue to solve this problem in the background. So when we get back to work, we should have a couple of ideas on how we could solve it. Splitting work into time slots should decrease the time needed on preparing the working solution.
Do something else to distract your mind - it would also help process your problem on an unconscious level
Use the rubber duck technique - it’s obvious
Learn how to use a debugger (if you don’t know yet) if you have to find a cause of a problem during a runtime
Gather as much data about the problem as you could. I mean you could get functional and non-functional requirements, some other constraints, and things that are important from a business perspective. All of that (a many more) will help you to design a proper solution.
Try to talk with a teammate from your project on the company - but prepare questions first in other to not waste your colleague’s time
Write the unit test first - that always works :)

Hope this list would help you solve problems faster. Point number one and two are the most important - do breaks to reset your power.

When Is a Feature Really Done?

Mon, 27 Mar 2023 00:00:00 +0000

Context

Have you ever argued with your teammate that some feature is finished and ready for production deployment? I faced it a couple of times from both sides of the roadblocks.

This situation is caused by a different definition of done definition. So let’s break it down into pieces.

When we could say that feature is finished?

There would be as many answers as the developers you asked. So I just want to show the levels that I spotted during my career. Let me clarify one more thing - we will be talking about production-ready software. So all things I describe do not apply to e.g. prototype of an application.

0. It’s implemented

I hope that this point shocked you. I had the same feeling when I saw that someone is deploying code (that was implemented 10 min ago) which is not been tested at all. Someone could say, that sometimes you need to deploy a hotfix to production. My answer is - something goes wrong in the development and internal tests process when you need to hurry to deploy a hotfix :)

1. It’s reviewed

I am ashamed that I said something similar one time after some CI/CD change I was doing did not work. I was inexperienced at that time… but that’s not an excuse. Remember, someone’s approval of the merge request does not absolve you of responsibility for the code.

2. It’s tested locally

For me, it’s something obvious, but I still see cases when untested code is deployed to prod. Remember, it’s always easier to discover bugs in the code you develop instead of debugging code that is running on prod for a couple of weeks or months.

3. It’s unit tested

I know that still people think that implementing unit tests is a waste of time and because of that unit tests are very often postponed or not implemented at all. For me code that does not have unit tests, it’s not finished.

4. It’s tested internally - by someone else that author

When you are reaching this point daily - it’s quite good we could say. When you are working on some application for a long time, then you could test “happy paths” only. Having someone else that could double-check it is a game changer.

But still there is a couple of things that could be improved

Let’s discuss them below.

5. You have logs with correct levels and additional metrics prepared

For sure, you would be observing how your new feature behaves on production to revert it when someone bad will start happening. To do it as fast as possible, prepare these logs even before deploying your code. In some complex cases, some additional metrics also would be welcome.

6. You are having feature-flag that covers things you developed

You will be sleeping well knowing that you could always revert your change without the need for reverting code and redeploying your apps. This approach would let you deploy it gradually e.g. per customer instead of doing “big bang” deployment.

7. Inform all people that could be interested before deploying a change to production

By doing this you are giving someone a chance of spotting things that won’t work or in the worst case will crash your application. Believe me, it could prevent a lot of problems in your daily work.

When you work for someone else. You should think about informing people that are making decisions about the app you are developing.

Some of them could be done even before you will start implementing new code

Fixing things without touching code will allow you to reduce the time of implementing it. I will present a couple of things below.

8. Prepare a couple of designs for your feature

Thanks to that you will be able to pick the best approach for a solution taking into consideration:

business requirements
technical limitations

9. Try to find a solution that lets you save time maintaining it over time

I saw such a situation very often… Someone implemented code that was doing what was intended to do. But it wasn’t prepared for any change that customers asked for in the future. I think this is one of the most underrated approaches for preparing code that could be easily maintained in the future.

In other words: if you don’t have a solution that considers the maintenance stage - don’t implement it. You will lose your time when implementing it and after that when fighting with problems. You should spend more time on a design to decrease the time needed for implementation.

10. “Implement code that could be removed very easily”

I don’t remember when I heard that rule, but it helps me implement code that is simple and generic. That gives me a couple of advantages. I can reimplement the entire code by removing it and simply implementing it from the scratch - using interfaces helps you establish contracts between modules. I am not afraid because of implementing something new, because I know it could be easily replaced by the next iteration of an idea - that would be improved thanks to the experience we gather.

11. Discuss your idea with more experienced developers

Before you start implementing new things. You could write it down in the task tracker your team is using. Then you can simply ask your teammates for some advice. When you are having people that are working on that system way longer than you, you will be getting a lot of pro tips about the module/feature you want to work on. Spreading knowledge about the system inside the team is very important.

Summary

In this post, I just gathered a couple of things that could help you build your own feature deployment checklist. Hope you would find something useful :)

Don't Build One-Off Solutions — Build Reusable Patterns

Thu, 23 Mar 2023 00:00:00 +0000

Context

I am sure that you are faced with a situation where you found a couple of classes that solve the same problem but in a different way. Also, when you implement or maintain similar modules you could find that entire code or specific classes look analogous. Here is how you could use it as leverage for your productivity.

Identify

Identifying such cases is key. Of course, without that, we can’t do the next steps for the improvements. Sometimes we have to refactor given code because is implemented in way different way, but after “normalization” we get the same code. I faced such cases many times, especially when working on legacy code.

Improve

We could do the improvement described in the previous sentence - refactor the code, so it could look very similar in every module. But this is only part of the improvement we could do.

Implement a pattern

Once we isolate a common class (a subset of methods in other words), then we could: check whether it’s doing a single thing and doing it right. Then we could divide the given class into smaller independent parts.

When we will be in this place we could introduce interfaces for all important classes. The complement step is to make those interfaces and concrete classes generic - a lot of languages are using “templates” or some corresponding method.

Replace old solution with generic one step by step

If you identified such classes in a couple of modules you should avoid replacing them at once. Does it step by step, so you could test everything properly and react to some problems if any would occur? This way you will discover them faster.

Summary

Thanks to the steps described above you will be able to implement something only once and use it anywhere else you need. Polymorphism is a game-changer here, it’s an increasing number of places that we could use our code later on.

There are a couple of benefits that we get from described approach:

we have less code to maintain in the long term
we need to spend less time doing it
we need to remember less about our codebase
we have only one file when we want to improve feature X
what’s more important we have one file to take a look at when searching for a bug culprit (we will be able to easily map file/class to a feature)
we could unit test our code way easier and faster
we decrease the complexity of the solution
we decrease the time needed to introduce a new person to our project
when having interfaces in place (that hides all other details under the hood), we could prepare very tiny documentation that will show connections between modules and interfaces :)
your team would be spending less time on code review and debugging bugs

You need to remember about couple more things:

it’s a process, and you should not try to do the last step in the first place, you need to take time to decouple code correctly (do it only when you know the system is your pocket)
remember to inform your teammates about changes - they should reuse your code to not waste time and don’t spend time on re-inventing the wheel

I know everybody loves spending time coding things. But by saving time you will be having it on doing another great thing with your app like preparing a design, discovering customer needs, helping your teammates, or just implementing another feature/fix way faster than planned.

Probably there are way more benefits from using the approach I described. You can share them with me of course!

Improve Your Workflow with Custom TODO Labels

Tue, 14 Mar 2023 00:00:00 +0000

For sure, you have thousands of TODOs left in your project. Today I will show you how to sort them out a little.

TODOs and why we need them?

Every popular IDE as e.g. IntelliJ or Eclipse allows us to create comments containing magic TODO or FIXME labels. All comments marked like this could be found in a special section in our IDE.

Of course, they are used for marking some parts of code for the future when we want to: add some features, do some improvements, or fix some small bug that could wait for now.

This small feature helps us save time when working on something important - we don’t have to open our task management tools to note it :)

Custom labels

I know those two labels could be enough, but as always we could distinguish a couple more of them. But …

How we could create a custom label?

To prepare an example I will use IntelliJ IDE but, you could apply the same patterns to other IDEs.

You need to visit Setting -> Editor -> TODO and just add a custom pattern e.g. \bimprove\b.*. After that, your IDE would be highlighting your custom labels as default ones.

Why should I create a custom TODO label?

I will give you a couple of ideas on how to use custom labels:

IMPROVE - To distinguish things that must be fixed or just should be done later.By using a such label we could mark some nice-to-have changes
QUESTION - We could use them to give some open questions about the code before pushing it to code review. I know we could use e.g. Gitlab UI to do it. But doing it in the code will help us save time and will leave some notes way closer to the code - for sure not all team members will look at the issue you create.
OPTIMIZE - Special label for those who love doing performance optimizations in the code
SECURITY - Found some security flaw, but don’t know how to fix it properly? You could mark that part of the code and share it with team members.

Let me know what other labels you will create in your project!

How to Choose Better Class Names

Sat, 25 Feb 2023 00:00:00 +0000

Did you ever ask yourself how you could save time on development stage? It would be very nice when you could implement some part of code way faster than now. Especially when you develop a lot of new features or extending existing ones. In this post I will show you very simple trick to achieve it!

Don’t you try to find name before you implement a class

The trick applies to structural programming too, but we are mostly using OOP on our daily basis. So I will use class as an example.

Imagine that we want to implement a class that would be doing some complex operations for us. Let’s say we gathered some requirements at the first step (I will give couple examples):

we want to take a photo from a webcam by using our browser extension
we want to process data in a way that output would be ready to show to our client
we want to validate URL based on rule configured by our client

In all those cases we will be able to divide code into a couple of classes. If we don’t want to use meaningless names like: controller, manager, service - then we could use that simple trick

Use some temp name

Yes, that is so simple. Use ‘Foo’ or ‘Bar’ for your class, implement whole logic encapsulated by this class. Of course, you need to remember that single class should do single thing, without any side effects. Also, remember about implementing unit-tests. Implementing both of them and sticking with very small class that have single purpose of use will let you create a name very quickly - once you finish implementing it or even in the middle of the process.

Remember: change the temp name to the correct one, before merging your code into the main branch.

Hope that you found it useful!

Understanding Common Software Development Errors

Wed, 18 Jan 2023 00:00:00 +0000

A programmer’s primary task is to automate the business processes of a given enterprise so that it ends up with a profit for the entity. Simple, right?

It is worth considering the amount of time spent fixing errors in code during daily work. Business owners invest in new functionality or modules, thus spending a significant amount of time correcting the same issues repeatedly, which may not align with the intended tasks or schedule.

Each programmer will probably answer that he would build new systems, modules, and functionalities rather than maintain the old system (which is not quite sure how it works and why).

Following this line of thought, the question we should answer is why bugs are introduced into software that is working on the production? What measures can we take to minimize such situations?

Ignorance of business and functional requirements

It’s fair to say that working on a project at a consulting company or a SaaS application should differ significantly. In addition to differences in working style. Identifying business requirements from conversations with the ordering party, end customers, or application owners is very similar in both cases.

It’s generally known that catching errors in assumptions at the requirements-gathering stage allows for the fastest and cheapest corrections. Hence the importance of properly taking the time to talk to customers/businesses to identify as many assumptions as possible.

A common mistake is starting development work without gathering requirements or before completing this stage. Another mistake is to rush through development, resulting in an ill-conceived code structure. Those causes could impact development velocity in the future. In other words, single feature development time for the same application would be longer and longer. Also, the number of errors introduced could increase because of it.

Misunderstanding of business and functional requirements

To avoid the above problem, work as closely as possible with the business to develop a common language and build a mutual understanding of what the application is supposed to do.

It is also good practice to indicate what the application will not do. That approach will help potential customers fully understand how the application would work.

At the stage of gathering and specifying requirements, the development team should cooperate with the business. The more mediators in communication, the worse (unfortunately).

Ignoring non-functional requirements

Premature optimization is a well-established antipattern. We use that term as an excuse for not preparing the technical requirements. Of course, emphasis on these requirements depends on the scale of the project.

For example, we could cause a negative evaluation of the project by not defining adequate response time for a module critical to the customer.

Insufficient shared knowledge of application modules

Nowadays, separate teams are working on a single application or system. In such a situation, teams must focus on sharing knowledge about every detail related to the developed app.

The matter worsens when working on a legacy project. Working in multiple teams that do not have the same knowledge about the product and the wrong dependencies between modules can only lead to one thing.

Misunderstanding of technology

It is common in legacy projects to encounter the use of a particular tool that contradicts the assumptions described in the documentation.

Introducing a new tool into our project connected with inadequate knowledge about that tool could lead to creating mistaken assumptions based on a couple of sentences from tool docs.

Unfortunately, both cases could end badly for our project.

YDD - Yolo-Driven Development

YDD is the opposite of the approach where we test changes before deploying them into production. “Let’s release to production, and then we’ll see”. Unconsidered changes can cause a lot of damage (not only to the code):

customers may quite often encounter an inadequately working application
changes made on the spur of the moment increase the likelihood of increasing links between modules of the application
such an approach to development is also very irresponsible (and so, at the end of the day, it is WE who will maintain the code)

Working without a plan

When there are hundreds of tasks in the backlog, and we don’t quite know which task is the most important from a business or technical perspective. The manufacturing team may have trouble planning their work. Not to mention identifying major changes that can solve several problems at once.

Work without metrics

Working with legacy code without a proper approach to testing changes. Combined with rushing changes into production. Without proper discussion of how a solution should work. Does this tell you anything? I hope that as few people as possible have encountered this approach to software development.

When the manufacturing team doesn’t have the time or doesn’t want to spend time on requirements identification and testing. There is nothing to dream about metrics that de facto save each developer’s time.

Properly built metrics allow for faster detection of bugs introduced into the software. In addition, we should create metrics that would describe our application (number of requests, latencies, etc.) and the business that we have (number of customers, number of errors reports, number of feature X usages).

Lack of sense of responsibility

In my opinion, the worst thing that can happen to a team is the approach we somehow instead of quality.

Making changes without thinking about architecture and infrastructure

When modules of the application are not well encapsulated then any changes in the code may cause a lot of problems. Performance problems or introduce a bug in a module we didn’t expect.

I can see from my observation that people start thinking about such things when their application is “burning”.

Human error

Of course, everybody could make some mistakes. But at least introduce the techniques described above: collection of requirements and introduction of tests or metrics. It will significantly reduce the effects of human error.

Summary

Hope that list will help you spot such things in your project. That would be a good start to improving it!