my thoughts

{ My Software Engineering -- some of my thoughts }

Think paper, paper, then code !

Most of the software engineering problems are solved in what I call the high-level brainstorming sessions. We basically walk into a meeting room and white-board our thoughts and come up with solutions. When things start falling apart, you better believe this happens in the last stretch of projects and it does work. Now the issue is that we as programmers do NOT do the similar type of exercise before a line of code is written?

I typically see developers get requirements in the form of a document or a user story or in the form of walk-by requirements. The next thing I see on developers’ screens is code editors or IDEs. Is that the right thing to do? You may say that you are advanced enough and that you like to dive into coding right away, but this happens even to the best of us. We fall into this trap and rarely step back and review our habits.

We have to go back to fundamentals. What did we do in school? Professors taught us to write down our thoughts and to show what we plan to eventually express in code. A piece of paper and a pen can do amazing things early in the game before a line of code is written. Even if it is a napkin, please use it and write down what you plan to do. It does NOT have to be pseudo-code; it could be just a bullet point list in English (or your choice of language) and a bunch of boxes/diagrams describing what you are planning to do when you put your hands on that keyboard in front of your choice of code editor or IDE.

This approach prevents potential confusions down the line and it can actually prevent show-stoppers in the 11th hour of your project. Whatever you write down on this piece of paper can also be used as a verification for your code because when you get into coding, you dive down too deep and forget the big picture; this piece of paper is there for you to keep you in check. When a tech lead ask developers how they implemented a specific requirement/user story, developers need to be able to articulate the implementation without showing any line of code. What’s the best way to show a solution and have discussions than a piece of paper with your approach. Then these discussions could lead to what I call “drive-by” mini demos and code reviews which are another great benefit, and that deserves its own blog post.

A developer may use the following argument against what I wrote here: “This is slowing me down. Why do I need to waste my time putting my thoughts on paper if I can just sit in front of my computer and start coding it?”

My response to the above argument would be: That’s fine; I am talking about guidelines here. These are not rules. It is up to you to choose when you want to use paper first and as your experience grows, you become better and better in making these decisions. There is no right or wrong; I am just providing some approaches/tools that help with the whole process. In many cases, this takes a bit of your time at the beginning and saves you a lot of headaches later in the project. At the end of the day, if a tech lead asks you to explain how you implemented something, you need to be able to articulate without showing code :)

What’s the conclusion? Think paper, paper, then code.

Microservice Architecture, but NOT microservice mindset?

We are on the same team!

Let’s say we as a company decide to implement the microservice architecture and we also decide to split the teams into domains for each team to own a domain (group of microservices). You may be a member of team A and I may be a member of team B and we are all on the same ship. There is a water leak in your area of the ship, but my side of the ship looks good.

What do we do?

Let’s help out each other because we are all members/passengers on the same ship. We are all going to the same destination :)

Microservice teams were created to pave domain boundaries at the architectural level, but it does not mean that we should create boundaries among members of different domain team members. Yes, the API contracts are definitions for how our services communicate, but for the sake of final destination, we need to tear down those boundaries when it comes to approaching each other for help and proactive integration.

It is beautiful to see ONE team in action especially in crunch time.

Micro in Micro-services

What does “micro” in the microservices mean?

How do you define what a microservice is? How do you define the boundaries?

This is not an exact science. However, when you get close to the boundaries of violating what the word “micro” means, you will know, and you will feel bothered making changes in that service because it will not feel right. It is still good to have some guidelines on defining the boundaries of your microservice. Here is the approach that I like to use.

Force yourself to write down on paper what your service does. Write it in first person to give it a little more emphasis.

I am the microservice A and I exist so that I can perform X.

This should be the first description in your API documentation so it is clear for your clients and it is also a good reminder for your team.

Let’s see an example. Let’s say you want to develop a “Subscription” microservice, and after some initial discussions you write the definition for that service:

“I am the Subscription microservice and I exist so that I can create, read, update, delete subscriptions and I also exist so that I can activate, deactivate benefits and terms for the subscription. I also exist so that I can correct the failed subscriptions into a good state.”

This definition is overwhelming. If the Subscription service ends up doing all of that work, then it is really not a micro-service. It is a macro-service. If the definition of your service has a lot of “ands” and “ifs” in the sentence(s), then you should worry about the size of this service.

Here is how this Subscription service could be turned into a micro-service.

“I am the Subscription microservice and I exist so that I can perform the CRUD operations on subscriptions.”

Now that your Subscription service is a micro-service, you need to introduce other services that will perform the remaining actions. For example, you can add the following services to perform the remaining actions:

“I am the Fulfillment microservice and I exist so that I can orchestrate the creation of a subscription and the fulfillment of that subscription which is really the activation and deactivation of benefits with a given subscription.”

“I am the Fulfillment-Recovery microservice and I exist so that I can recover the failed subscription into a good state.”

This is just one example of how you can define the boundaries for the “micro” in the microservices. One may argue that you can break the above services into smaller services, and in my opinion that’s where you are on the other spectrum where your microservices would be turning into nano-services. That is ok as long as you don’t get over-excited and negatively impact performance. If you go in this direction too much, that’s where you are starting to feel the overhead of too many RESTful calls chained together and each http call over the wire adds up. That’s where you need to be very realistic and decide how much you are gaining by doing this given your use cases.

Another way to more closely define the “micro” in your microservice is to define the API routes for all the actions that you mentioned in the definition of your microservice. If you go through this exercise, you quickly discover that the API routes for the original long definition of the Subscription microservice are not going to stay RESTful. That is your signal to start breaking up that service into smaller services.

In conclusion, introduce some guidelines within your company on how to define what a microservice is and keep each other in check when adding new services and when adding functionality to you existing microservices.

Set high standards for yourself — Challenge yourself

I have been at my current company long enough to get too comfortable, but is that the case?

The years I have spent in my current job feel very much like 3–4 jobs. The company went through different of senior leaderships roughly every 4 years. On top of that, there is the technology aspect and its changes over the years, and different types of projects I have been part of. All of these things painted a picture in my head as if I changed jobs 3–4 times.

What is the secret to still getting “New Employee” jitters every week even after being with the company for so long? What is the secret to challenging yourself?

(1) Don’t wait for your leaders to challenge you. You need to challenge yourself from week to week.

(2) You need to care.

(3) Appreciate what you and your team accomplished, but never be fully satisfied; there is still a balance to this. Look at this from a positive angle. Look at it as an opportunity.

(4) Don’t judge somebody else’s engineering efforts that you inherited; you don’t know what circumstances they performed that under. Instead focus that energy to try to understand it, identify what can be improved and improve it; this will keep you on the edge because improving something you inherited is harder than just building it from scratch because you might not have an option to build it from scratch. You will learn how to plan it and improve it incrementally.

(5) Create a great team so that you are in a room with a group of people who are smarter than you. For example, as a solutions architect and a software engineering leader I may be the one making final decisions (if necessary) on designs/solutions, but every day I learn something new from my teammates and that’s a great feeling.

All of this adds a bit of that uncertainty and a new boost of energy from week to week. This is enough to still get a bit of “New Employee” jitters that make us prove ourselves over and over again.