My preference for an iterative approach is rooted in its ability to design solutions that meet current business needs while emphasizing simplicity. This simplicity allows for quick adaptations during subsequent iterations, taking advantage of the expansive design space. The iterative process also enables me to gather real feedback from production usage, facilitating meaningful optimizations based on actual needs. Upon receiving feedback, I can enhance the solution, aligning it more closely with real-world requirements.

Additionally, the iterative design minimizes risks in software engineering management through its ability to promptly identify and address potential issues early in the process. As a result, the overall risk associated with the project is diminished. Collecting feedback from actual production usage enables swift adjustments with minimal effort, given the straightforward and easily modifiable nature of the solution.

On the flip side, a perfective design hinges on anticipating the majority of needs, which may not materialize as expected. This can result in added complexities and resource investments prior to the system going live. Such additional efforts can adversely affect the time-to-market, as more time is devoted to the solution. Moreover, if design modifications are required after going live, it could prove challenging since the unknown factors might not have been thoroughly considered in the initial design.

Embracing a perfect design mindset may result in inaccurate predictions of future requirements, potentially leading to the misallocation of resources. Subsequent corrections and adjustments may be necessary as the initially anticipated business needs might differ from the actual ones. There is a risk of expending resources on refining solutions based on inaccurate predictions instead of addressing genuine business requirements.

What you envision as the end might not be the final outcome; there are numerous possibilities within your business.

Your design should not impose constraints on the business; instead, it should reserve flexibility to foster the expansion of business possibilities. Adopting a perfective design mindset may involve defining the business's end goal, but in reality, business requirements evolve over time. Therefore, the design should be adaptable to the evolving needs of the business, as facilitated by the iterative mindset.

To address this issue, my approach involves establishing a precise priority for the current business need and concentrating solely on the present without attempting to predict future needs. By adopting this strategy, I aim to reserve more design space for future iterations while optimizing the utilization of team resources. This ensures a more flexible and adaptive development process, allowing for effective adjustments based on real and evolving business needs.

In conclusion, my software engineering philosophy centers on finding a balance between adaptability and precision, ensuring efficient resource utilization and effective adjustments based on real-world business needs.

From my experience, dealing with a method that lacks clear boundaries and encapsulation can indeed create a steep learning curve. When all the logic is intertwined without a clear separation, it becomes challenging to comprehend the method. This coupling of diverse logic forces the reader to shift focus continually, making it harder to understand the method's flow and functionalities.

The method ignores a lot of implementation details but imagine you need to deal with different validation, business logic, error handling, etc.

In the above example, the placeOrder method, in its current state, encompasses a multitude of responsibilities, from inventory management to payment processing and order creation, resulting in a convoluted method. This intertwining of diverse functionalities heightens complexity, making comprehension and maintenance challenging.

Improving readability and maintainability in code hinge on two main strategies: extraction and encapsulation.

Extraction involves breaking complex code into smaller, more manageable pieces, making it easier to understand. Each extracted part handles a specific task, simplifying the overall structure and allowing readers to focus on the main logic.

Encapsulation groups related data and functions within classes or modules, creating boundaries that control access. This helps abstract away complexities, making it easier to interact with these components without understanding their intricate details.

Together, extraction and encapsulation create a more organized and understandable codebase, enhancing readability, maintainability, and the overall quality of software systems.

Take the above example again, to organize the logic and data flow, one effective approach is method extraction. By understanding the method's responsibilities, we can extract distinct actions into smaller methods:

• Validate Stock

• Process Payment

• Create and Validate Order

• Send Notification

Breaking down the placeOrder method in this manner creates a cleaner structure, highlighting the four primary steps. This modular approach allows readers to grasp the method's flow at a glance and delve into specific methods for deeper insights.

Furthermore, if the class seems burdened with excessive responsibilities, another step is to organize these extracted functionalities into distinct domains—such as Stock, Payment, Order, and Notification—and encapsulate each within a dedicated class. Following this, an orchestrator class can coordinate these domains within the placeOrder method.

By employing this approach, the codebase becomes more cohesive, less coupled, and easier to understand, fostering a more organized and maintainable architecture.

Extraction and encapsulation work hand in hand to distribute complexity effectively among the appropriate domains. By breaking down complex functionalities into smaller, cohesive units through extraction, and then encapsulating related data and operations within specific domains, we can effectively manage and organize the complexity within a software system. This approach ensures that each domain is responsible for handling its own complexities, resulting in a more organized and maintainable codebase.

To sum up, improving code readability and maintainability relies on two main principles: extraction and encapsulation. Extraction involves breaking down complex code into smaller, manageable parts, while encapsulation groups related functions and data within classes or modules. Together, these techniques create a more organized and understandable codebase, enhancing the overall quality of software systems.

After multiple layoffs, I was thinking about what I should do and what I could do other than my full-time job. I found writing quite interesting and I like sharing my thoughts. Therefore, I am trying to start this blog to share my thoughts about software engineering and help people learn practical software engineering knowledge which is useful in a software engineering career.

Back to the topic, In 2023, I wrote 41 articles in Awesome Software Engineer across different topics including API, architecture, software design, and soft skills.

For the subscription numbers, the following are the statistics:

• 2022: 199 subscribers

• 2023: 591 subscribers

Total traffic in 2023:

The following are some featured articles in 2023:

This year 392 new readers subscribed to Awesome Software Engineer which is already an impressive result for me. Other than posting the content on LinkedIn, I haven’t promoted my blog that much. So, I am happy with this result and hope Awesome Software Engineer gets more subscribers in the next year. This might need the whole community’s help and I am willing to get any feedback from all of you. Continuous improvement is important for software engineers and feedback helps people to improve themselves.

In 2023, I also moved some of my content to Medium

• https://medium.com/@raychongtk - Follow my account to support my work

Apart from that, I organized my content into categories.

• https://www.awesomesoftwareengineer.com/

• https://github.com/raychongtk/awesome-software-engineer - Give a star to my GitHub repo to support my work

In the coming 2024, I hope my content can inspire more software engineers to help you speed up your learning track in the software engineering area. Wish all of you a Merry Christmas. Don’t forget to like, share, and subscribe to Awesome Software Engineer. Thanks!

Share Awesome Software Engineer

In our industry, chaos often reigns supreme, with intricacies and disorder prevailing. As software engineers, our role is akin to being architects of order amid this chaos. We leverage our software engineering skills not merely to navigate the complexity but to actively organize the chaos, molding it into a coherent and simplified structure. It's a profession where the artistry lies in transforming disorder into consistency and simplicity, crafting solutions that stand resilient in the face of the intricate and messy landscape of our industry.

In my software engineering journey across various companies and diverse codebases, I've encountered projects with well-defined coding standards as well as those lacking any standardized approach. The impact of having a coding standard versus the absence of one is substantial and significantly influences the development experience.

When working on a project that adheres to coding standards, I experience a sense of consistency and ease of understanding. I don't have to grapple with diverse coding styles, terminologies, or structures. Everything is well-coordinated and aligned, providing a seamless experience. The project offers a smooth journey, sparing me the need to invest significant time in studying the intricacies of the code because it is clear and straightforward. I can effortlessly locate what I need in the codebase and navigate through the project with ease.

Picture a project with coding standards as a harmonious symphony. Everything aligns seamlessly—coding styles, terminologies, and structures dance to the same rhythm. This uniformity transforms the codebase into a clear and comprehensible masterpiece, allowing developers to focus on the logic.

On the flip side, when I engage with a project lacking coding standards, it feels like navigating through a chaotic landscape. Everything is in disarray, making it challenging to acquire a solid understanding. Numerous coding styles coexist within a single project, and the structure and logic flow vary widely. Even the terminology, such as domain, entity, and DO (data object), often points to the same concept— the database object. This lack of uniformity in the codebase poses hurdles for learning and complicates the process of introducing new features or modifying existing behavior. The resultant confusion extends to understanding the current logic and structure. Moreover, it triggers numerous discussions on coding styles during code reviews, adding another layer of complexity to the development process.

A project without coding standards resembles a chaotic carnival. Divergent styles and terminologies introduce confusion, slowing down development and increasing the likelihood of errors. It's a battlefield where understanding the code becomes a challenge, leading to suboptimal results.

In short, projects with clear standards offer a symphony of consistency, providing an effortless and efficient experience. Conversely, projects without standards resemble chaotic carnivals, introducing confusion and impeding progress. Embracing coding standards becomes not just a choice but a compass guiding developers toward clarity and success in the coding wilderness.

Share Awesome Software Engineer

I started contemplating how to better utilize my time on the team. I recognized that software engineering involves not just coding but also other skills like communication, documentation, innovation, etc. From that, I discovered that writing is a powerful skill to facilitate communication and optimize time.

The importance of writing can be summarized in the following points:

• Scaling Yourself: Creating effective documentation not only helps in avoiding repeated questions but also saves valuable time. It captures thought processes, architecture, decisions, and ideas, acting as a reference for both yourself and others. Even when you are on vacation, colleagues do not need to disturb you; they can find answers in the documentation. This, in turn, enables you to better allocate your time and contribute more to other important tasks. Writing is the most scalable way to influence others, as people will read your content and might be inspired by it.

• Saving People’s Time: Comprehensive documentation reduces back-and-forth communication and enhances information retrieval efficiency. Serving as a knowledge base, it allows people to efficiently search for keywords and locate content. This documentation proves invaluable for onboarding new team members, troubleshooting issues, and understanding the project's evolution over time. Additionally, good writing skills contribute to summarizing rich content in a concise manner, saving people's time and keeping everyone aligned, especially in a chat context.

• Conveying Ideas and Creating Consensus: Effective communication is crucial in any collaborative environment. For abstract and complicated ideas, writing provides a structured way to convey the idea to other stakeholders, whether in a design document, proposal, or project progress report. Clear documentation makes it easier for everyone to understand intentions and create consensus, especially in decision-making processes, as it explains the rationale behind a choice or direction.

This makes me feel writing is actually a part of software engineering. Software Engineer or Writer? Writing is a subset of Software Engineering, so software engineers should acquire better writing skills. The way you summarize or structure the content helps facilitate communication between different stakeholders and makes people work more efficiently.

What else do you think writing can help in your software engineer career?

Share Awesome Software Engineer

In the realm of software development, projects often begin with a straightforward approach, but as new features are introduced, code complexity tends to grow. The original design may become inadequate to accommodate these new requirements. When engineers encounter this situation, they face two options:

1. Refactoring: This involves revisiting the existing codebase and improving its design to align with the new requirements. It's about proactively managing and reducing complexity as it arises.

2. Extending the Existing Design: Alternatively, engineers can choose to patch the existing design to accommodate new features, even if it doesn't fit seamlessly with the original structure. This approach can lead to growing chaos and complexity over time.

Consider the diagram below: In the case of active refactoring, engineers address complexity as it emerges, ensuring that it remains under control. However, without regular refactoring, complexity accumulates until it becomes unmanageable, resulting in a bloated codebase that no one can decipher or extend. At this stage, overhauling the entire project becomes necessary, as opposed to the more incremental and sustainable practice of refactoring.

Refactoring should be a continuous practice and not something left until the code has become excessively bloated. It's essential to identify refactoring points throughout the development process. While pinpointing these points often relies on experience and judgment, some common indicators can help guide your decisions:

1. Difficulty Adding New Features: If you encounter challenges when trying to integrate new features into the codebase because the existing structure doesn't easily accommodate them, it's a clear sign that refactoring may be necessary. Refactoring can make the code more flexible and adaptable.

2. Code Maintenance Challenges: When it becomes challenging to read and understand the code or fix issues that arise during live operations, it's a strong indicator that the code may need refactoring. Complex, convoluted code is prone to errors and difficult to maintain.

3. Lack of Clarity: If team members frequently seek clarification on the logic and struggle to extend the codebase, it suggests that the code's design and organization may be unclear or inadequate. Refactoring can improve code clarity, making it easier for others to work with.

In essence, a refactoring point is a juncture where the code's current state impedes its maintainability, readability, or adaptability. Addressing these issues as they arise, rather than waiting for code bloat, helps maintain a healthy and manageable codebase throughout the software development lifecycle. Regularly identifying and addressing refactoring points is a proactive approach that contributes to code quality and project sustainability.

Refactoring serves as an ongoing improvement process that ensures the code remains current, comprehensible, and maintainable. Continuous refactoring brings about several benefits:

1. Enhanced Developer Experience: Continuous refactoring improves the overall developer experience. New team members can easily onboard and start working with the codebase. This streamlines the process of understanding the code's structure and logic, leading to a happier and more productive developer team.

2. Improved Maintainability and Readability: Continuous refactoring ensures that the code consistently mirrors the actual behavior required by the business. It achieves this by presenting the code in an organized and straightforward manner. This level of clarity makes it effortless for developers to read and understand the code, reducing the likelihood of errors and simplifying maintenance tasks.

3. Enhanced Engineering Efficiency: When code is regularly refactored, developers don't need to invest excessive time and effort deciphering its behavior when working on new features or addressing issues. This heightened efficiency allows for faster development cycles and quicker responses to business needs.

In summary, continuous refactoring is a pivotal practice in software development that fosters a positive developer environment, bolsters code maintainability and readability, and ultimately leads to increased engineering efficiency. It ensures that the codebase remains a valuable and adaptable asset for the organization as it evolves to meet changing business requirements.

Imagine when internal users trigger a “create order” request in an internal portal, and the “create order” request involves 10 requests from different microservices to complete the action. If one request takes 1 second to complete, it takes 10 seconds in this case.

Triggering a request in the frontend and taking 10 seconds to respond back to the frontend is really hurting UX a lot.

Let’s take a step back. Do we really need to execute the requests sequentially? The requests do not have a dependency, they can all be executed in parallel. In this case, if we change the design to parallel requests, the performance will be improved significantly.

With parallel requests design, every request is assigned to a dedicated thread and executed concurrently. After submitting to a thread pool, the program waits for all the results to come back. When all the requests are completed, the program aggregates the response and returns it back to the frontend. In this case, 10 seconds waiting time can be reduced to 1 second in the best case as we don’t need to execute the request one by one. Instead, we execute the 10 requests to 10 different services simultaneously.

What if we have a dependency between some requests? In this case, we can mix serialization and parallelization together.

When mixing serialization and parallelization together, we can still optimize the processing time a lot. But this is not going to work when the requests are tightly coupled with each other. Because you always need to wait for a response in order to proceed with the logic flow. In this case, you may consider other optimization strategies.

In summary, if you have an API that needs to integrate with many services and they don’t have a dependency on each other. You can consider this optimization approach in order to reduce the waiting time.

Serialization means executing a series of tasks one after the other within a single thread. In other words, these tasks are executed sequentially, with one task starting only after the previous one has completed.

Pros

• Simple: Serailization is simple and straightforward to implement.

• Resource Efficiency: Unlike a multithreaded program, serialization uses a single thread to handle a series of tasks, so it requires fewer system resources.

Cons

• Slower Execution: It executes the tasks one by one. So, it only starts a new task when the previous task has been completed.

• Inefficient Resource Utilization: Serialization may not efficiently utilize system resources in a system with a multicore CPU.

Parallelization

Parallelization means executing a series of tasks in multiple threads, one task is assigned to a dedicated thread. In other words, these tasks are executed in parallel. This approach allows for better utilization of multiple CPU cores and can lead to improved performance and responsiveness in applications.

Pros

• Improved Performance: One of the primary benefits of parallelization is improved performance. By executing tasks concurrently on multiple CPU cores, you can significantly reduce the overall execution time of a program.

• Resource Utilization: Parallelization efficiently utilizes available hardware resources. It enables better use of multi-core processors and can lead to more efficient resource utilization in distributed computing environments.

Cons

• Overhead: Managing threads comes with overhead, including context switching and memory usage. This overhead can offset performance gains for small tasks.

• Complexity: Parallelization introduces complexity into software design. Managing multiple threads, coordinating their activities, and handling synchronization can be challenging.

• Debugging: Debugging parallel code can be more challenging and time-consuming. Issues may be difficult to reproduce and diagnose.

In summary, they both have their pros and cons. Choose the approach wisely depending on different use cases. The key is to understand the nature of your tasks and the trade-offs involved. In many cases, a combination of both techniques may be appropriate. Ultimately, the choice should align with your application's specific needs and goals.

Single Requests

In the Single Requests approach, API consumers initiate multiple requests independently. For instance, if you need to send inbox notifications to various users, under this design, each request must be sent one after the other. However, this method may not be the most efficient. Each request incurs network overhead and necessitates waiting for individual responses. Particularly in scenarios where the same request needs to be repeatedly sent to the API provider, this approach becomes inefficient and resource-intensive.

Batch Requests

On the other hand, the Batch Requests design streamlines the process. When, for instance, inbox notifications need to be sent to a hundred users, this approach requires only a single invocation of the notification API. This optimizes network overhead significantly. Yet, it introduces complexities, such as managing invalid requests within the batch and the intricacies of the overall design. Error handling and determining the source of failures become more intricate when compared to the Single Requests design.

The Right Choice

Choosing between these two approaches isn't straightforward and depends on the specific context. Neither approach is universally superior; rather, each has its strengths for particular use cases. The decision hinges on factors such as the nature of the operations, the frequency of requests, and the balance between network efficiency and design complexity.

This is a simplified mental model that could help you choose the right API design. To find the optimal solution, consider a hybrid approach. Employ Single Requests for simple, critical operations, and leverage Batch Requests for tasks involving a large volume of requests that can benefit from reduced network overhead. Ultimately, the best approach aligns with your application's unique requirements and goals.

Share Awesome Software Engineer

My approach to delegating tasks involves several key steps:

1. Gather information and set a clear expectation

When delegating a task to another engineer, there might be a lack of clarity on how to proceed. To address this, my usual approach involves gathering all necessary task-related information prior to delegation. This ensures that when the new engineer assumes the task, they have a comprehensive understanding of the required steps for its completion. Alternatively, It is better to outline specific instructions to guide them toward the relevant information sources. Subsequently, it becomes imperative to establish distinct expectations, encompassing the task's scope and anticipated outcomes. This approach fosters a mutual understanding of the intended results and minimizes any potential uncertainties. By adhering to this method, effective task delegation is achieved, circumventing the need for prolonged back-and-forth communication. Furthermore, this proactive clarity assures that the task progresses correctly and aligns precisely with the desired outcome.

2. Step in when challenges arise

Step in when a task encounters obstacles or unforeseen incidents. Despite delegating the tasks, you retain ownership and bear the responsibility of assisting others in resolving blockers or unexpected situations. Your role involves ensuring a seamless engineering process during development and aiding your team's focus on their essential tasks.

3. Actively progress monitoring

Delegation is not a complete transfer of ownership; instead, it expands the support network. Therefore, maintaining an active role in monitoring progress is crucial. Regular progress checks allow me to gauge the trajectory of tasks, verify alignment with objectives, and offer timely assistance as required.

4. Provide constructive feedback during code/design review

Delegation benefits both the person assigning tasks and the one receiving them. As a delegator, I gain the freedom to focus on important matters, while the delegatee gains valuable experience and added responsibilities. Giving positive feedback is crucial for their growth, and constructive feedback helps them improve further. Feedback also helps align expectations for outcomes. While it might require initial effort, the rewards increase over time. As the delegatee improves, the delegation process becomes smoother in the future.

In summary, delegation is more than just giving tasks—it's a collaborative strategy that promotes growth. By gathering information, staying engaged, tracking progress, and giving feedback, delegation becomes a rewarding experience for everyone. It helps with growth, efficient tasks, and teamwork in the ever-changing world of software engineering.

Share Awesome Software Engineer

The underlying purpose of architecture extends to the identification of intricacies, risk assessment, communication, and the strategic allocation and integration of resources.

Integration and Allocation of Resources

A pivotal consideration in architectural decisions is an awareness of existing engineering resources. Resource availability determines whether the team possesses sufficient engineering capacities to facilitate a timely feature rollout, thereby impacting time-to-market. During the architectural phase, it becomes imperative to measure the necessary engineering resources required and assess their value proposition. Given the precious nature of engineering resources, strategic investment in the right areas is crucial to enhance product value. If a feature holds substantial significance, a proportional augmentation of resources can be allocated. This necessitates the seamless integration and judicious allocation of all available resources.

Management of Risk

Once the resource allocation is outlined, risk evaluation becomes paramount. The architecture design phase mandates a comprehensive assessment of potential risks, necessitating trade-offs and decisions to be made. The acceptability of these risks upon deployment becomes a vital consideration. By effectively mitigating explicit and critical risks, it becomes feasible to control the impact of challenges that may exceed the architecture's capabilities.

Control of Complexity

A fundamental facet of architecture pertains to complexity management. Each design inherently carries a level of complexity, but not all levels are tenable for a given team. During the architectural blueprinting, it becomes imperative to account for the team's proficiency and resource availability. This strategic consideration aids in maintaining a complexity threshold that aligns with the team's capabilities, fostering a sustainable architecture. Architecture is not a universal solution but varies depending on the situation. To create an effective solution, we should eliminate unnecessary complexity and create a design to address the specific problem we intend to solve.

Communication and Collaboration

Architecture acts as a communication tool connecting team members, stakeholders, and various technical and non-technical groups engaged in the project. A clearly outlined design document plays a crucial role in ensuring that everyone comprehends the project's framework and objectives.

In a nutshell, architecture's purpose extends beyond engineering challenges. It aids in resource optimization, risk mitigation, complexity control, and effective communication, making it a pivotal factor in successful project development.

Share Awesome Software Engineer

• Abstraction-driven Design

People who champion the abstraction-first method are all about thinking ahead. They're like the fortune-tellers of software - they try to predict future needs and design solutions that can be reused down the line. It's like building a universal toolkit for future problems. But here's the kicker: these predictions are made in a complex, ever-changing business world. Sometimes, reality takes a different route, and suddenly that fancy design doesn't fit the puzzle anymore and leads to a rigid design that is hard to adapt.

• Simplicity-focused Design

On the flip side, we've got the keep-it-simple believers. They're the pragmatists of the software engineering world. They say, "Hey, let's not complicate things until we have to." They build straightforward, no-nonsense solutions that are easy to wrap your head around. These guys are all about preserving design space for future extension. It's like having a roomy backpack that you can stuff with new tools whenever you need them. Of course, this approach comes with a catch – you need to roll up your sleeves and refactor stuff every now and then to stay up to date with the ever-changing business scene.

The diagram depicts the trajectory of the simplicity-focused approach. Beginning with a specific and tangible design, this methodology iteratively hones the solution over time. This approach resonates with scenarios where simplicity offers greater appeal than elaborate abstraction, except when abstraction genuinely simplifies matters.

In a rapidly expanding product company, simplicity in design is key to allowing ample space for future iterations. Given the swift evolution of product requirements, a simple design approach is preferred. Delving too deeply into future possibilities from the outset can inadvertently constrain the design space, complicating understanding for others. This occurs when code becomes overly abstract and generalized.

To elaborate, "abstract and generic" signifies an intention to address multiple potential problems, whereas "concrete and specific" pertains to addressing a singular issue. Applying a versatile solution to a single problem elevates cognitive load – the mental effort required to comprehend the intricacies. Striking a balance between abstraction and specificity thus emerges as a crucial consideration in managing the design space effectively.

The trade-off is evident: increasing abstraction might obscure comprehension due to numerous assumptions embedded in the design. Consequently, it reduces future expansion possibilities and amplifies the ripple effect of logic changes. In contrast, starting with a concrete solution promotes clarity, facilitating accessibility even for individuals lacking specialized backgrounds. This approach also fosters a more expansive design space, conducive to accommodating future extensions. Adaptation to evolving business needs can be achieved through strategic refactoring.

It's crucial to recognize that design space contracts over iterations as complexity accumulates. Establishing a refactoring culture becomes paramount to maintaining a reasonable design space and ensuring future extensions remain feasible. Typically, a concrete solution offers a broader design space, whereas abstraction's inherent assumptions restrict it.

If you're finding it challenging to make changes when new requirements pop up, that could be a sign that your code needs some refactoring. It suggests that your design space might be too limited, making it tough to make necessary iterations smoothly.

In conclusion, software engineering offers two distinct approaches: abstraction-driven design and simplicity-focused design. Striking a balance between predicting future needs and maintaining adaptability is key. The challenge lies in managing design space as complexity grows, necessitating occasional refactoring. Agility, openness to change, and a pragmatic mindset are essential for optimizing design and creating resilient software solutions that can evolve alongside evolving business requirements.

Share Awesome Software Engineer

In the realm of software engineering, a problem can often be immense. When embarking on problem-solving, comprehending the scope of the issue becomes paramount. This encompasses the problem space, a comprehensive domain encompassing all aspects of the problem. Imagine it as a landscape with various contours. As software engineers, it's crucial to skillfully deconstruct a problem into manageable fragments. This practice not only simplifies complexity but also allows teams to concentrate on specific and controllable components.

An immense problem space is a signal of potential intricacies and implies multiple avenues for resolution and various directions to explore. However, an abundance of choices without clear direction can confound the team. Visualize a map with numerous paths – without guidance, the team can lose their way, and decision-making becomes a daunting task. The result? A team adrift, grappling with an assortment of details and losing sight of the core issue at hand. So, what is the core problem that the team aims to solve? This is an important question that determines how far a team can go.

Contending with an extensive problem space necessitates a dual approach: breaking down and establishing direction. First, the task involves fragmenting the immense problem into smaller, more approachable sub-problems. Next comes the crucial step of defining a precise direction to guide the team's efforts. Ultimately, all the components are harmonized into a cohesive whole. This strategic methodology aligns with the age-old "divide and conquer" philosophy.

To make it short, the significance of these steps becomes apparent for problem-solving:

• Problem Decomposition: Divide and Conquer emerge as a powerful technique for unraveling complex issues, transforming them into manageable parts.

• Prioritization: By prioritizing tasks, teams identify key objectives and allocate attention where it matters most.

• Decisive Action and Focus: A well-defined direction sharpens focus, streamlines tasks, and eliminates superfluous steps, guiding both team and product towards desired outcomes.

• Iterative Approach: Problem-solving rarely follows a straight line; iterative cycles enable adjustment and growth. Flexibility remains essential as teams refine strategies based on insights gained.

In summary, grappling with intricate problem spaces in software engineering necessitates a strategic approach. Understanding the scope of the issue, fragmenting it into manageable components, defining a clear direction, and embracing the "divide and conquer" concept is integral to effective and efficient problem resolution.

Share Awesome Software Engineer

Pagination is a valuable approach for enhancing data retrieval performance. In a previous post, I discussed the implementation of Pagination in API design. However, it's important to be aware of a potential pitfall associated with this pagination technique. In software engineering, there are two primary types of Pagination: Offset-based Pagination and Cursor-based Pagination.

Offset-based Pagination

Offset-based pagination, the technique I previously introduced, offers simplicity in design and flexibility for navigating to any desired page.

This visualizes how offset-based pagination navigates pages. With this design, users can simply jump to any page that they want.

select * from target_table where x > y order by id skip 0 limit 8;

select * from target_table where x > y order by id skip 8 limit 8;

select * from target_table where x > y order by id skip 16 limit 8;

select * from target_table where x > y order by id skip 24 limit 8;

select * from target_table where x > y order by id skip 32 limit 8;

However, as the offset value increases, retrieving subsequent pages becomes slower. This is because each retrieval requires skipping a certain number of records, resulting in performance degradation. This impact can be especially obvious when working with large datasets or when the offset values are high. It's crucial to consider these limitations and explore alternative pagination techniques to mitigate the performance issues associated with offset-based pagination.

If your system uses offset-based pagination and suffer performance issues, you should talk to your product manager to set a limitation on how deep a user can navigate between pages. The more pages that a user skips, the slower the response is.

Or, consider using the below alternative to design pagination.

Cursor-based Pagination

To address these challenges, an alternative pagination approach called cursor-based pagination emerges as a viable solution. Unlike offset-based pagination, cursor-based pagination offers improved performance and stability by leveraging unique cursor values associated with each record. It enables more efficient and consistent queries, especially when dealing with large datasets.

In cursor-based pagination, random page navigation is not allowed. Instead, only linear access is allowed in this design which users can only navigate to the previous page or the next page. It can provide better performance compared to offset-based pagination, especially when dealing with large datasets.

select * from target_table where x > y order by id limit 8;

select * from target_table where x > y and id > 8 order by id limit 8;

select * from target_table where x > y and id > 16 order by id limit 8;

select * from target_table where x > y and id > 24 order by id limit 8;

select * from target_table where x > y and id > 32 order by id limit 8;

However, it's important to note that implementing cursor-based pagination can introduce additional complexity compared to offset-based pagination. Maintaining and managing unique cursor values for each record requires careful consideration to ensure their integrity and uniqueness throughout the pagination process.

jOOQ did a comparison for the performance. If you are interested in the detailed comparison, go check out this blog.
Ref: https://blog.jooq.org/faster-sql-paging-with-jooq-using-the-seek-method/

When deciding which pagination technique to employ, it's crucial to evaluate the specific requirements and characteristics of your application. Consider factors such as dataset size, user navigation patterns, and the trade-offs between performance and implementation complexity. By carefully analyzing these factors, you can determine the most suitable pagination approach for optimizing data retrieval performance in your software system.

In the realm of software development, backend systems store vast amounts of data, and it is the responsibility of software engineers to design APIs that retrieve this data from databases.

When dealing with small datasets, some novice engineers may design APIs that fetch all the data from the database in a single operation. This approach works fine with small data sizes since it doesn't lead to performance issues.

However, when the database contains millions of records, retrieving all the data in one go can result in slow query performance or even OOM. Slow API responses not only hinder user experience but also undermine the reliability of the API, potentially eroding customer trust.

To address this issue and improve performance, a recommended solution is to redesign the API using pagination.

In this enhanced design, a large dataset is divided into smaller chunks, and the data is retrieved incrementally using pagination. For instance, the first API call fetches the first 8 records from the initial page. If users need to access the second page, another API call is made to retrieve that specific page.

By adopting this approach, the API retrieval performance can be optimized. In contrast to the previous method, which retrieved the entire dataset at once, the improved design fetches only 8 records per API call, effectively controlling the data size and enhancing performance.

💡 Do you know what’s the hidden performance issue with using this type of pagination? Share your thoughts in the comment section!

In summary, pagination is a technique that divides large datasets into manageable pages, improving retrieval performance, controlling data size, and enhancing the user experience when dealing with substantial amounts of data.

Designing software architecture requires careful consideration of various factors to ensure its effectiveness. In this post, I will share some ideas for creating a software architecture that can adapt to different conditions and resources.

When designing architecture, there are several important aspects to consider:

Team Resources

It is crucial to take into account the resources available within the team. Even with great architectural ideas, lack of resources can prevent successful execution. For example, a small team cannot build something as complex as Google. Therefore, the architecture design should align with the current team resources and the knowledge level of the engineers involved.

Time-to-Market (TTM)

The architecture design should be mindful of the overall development time required to bring the product to market. If there are strict time constraints, it would not make sense to implement an architecture that requires significantly more time than available. TTM is a critical factor as it directly impacts revenue generation. If an architecture cannot adapt to this constraint, it should not be considered.

Business Adaptation

The architecture design should be aligned with the current state of the business. For instance, companies like Airbnb started with a monolithic application and later evolved into microservices and a combination of micro and macroservices. By considering the business scope, the architecture can be tailored to meet the specific needs of the company. Designing an architecture for a significantly higher workload than the current demand would result in unnecessary investment and inefficiencies.

Airbnb Architecture Evolution:

• Monolith (2008 - 2017)

• Microservices (2017 - 2020)

• Micro + Macroservices (2020 - Present)

Ref: https://www.infoq.com/presentations/airbnb-culture-soa/

The evolution of Airbnb's architecture exemplifies how a large tech company adapts its architecture to align with its evolving business needs. As the business grows, the architecture evolves accordingly. This demonstrates the importance of periodically reassessing the existing architecture, removing outdated elements, and adapting it to meet new requirements.

Creating an excellent architecture begins with establishing a solid foundation. While it's important to plan for future needs, it's equally essential to invest time wisely and prioritize current business demands. Predicting the future is challenging, and dedicating significant resources to shaping the architecture for hypothetical scenarios may not be efficient.

One might argue that designing for future scalability is necessary in order to become a successful company. While this is true, it's important to balance long-term goals with current priorities. The architecture can be designed with future scalability in mind, but implementing it immediately without actual business needs may not be the best approach. In a fast-growing company, it's crucial to allocate resources effectively and adapt the architecture when the business demands it.

Share Awesome Software Engineer

As software engineers, dealing with software architecture is crucial in our day-to-day work. It involves making decisions about components like caches, message queues, search engines, or even transitioning from a monolithic to a microservices architecture. While we may know how to implement these components, it's important to understand why we need them.

Let's consider the example of a cache. Some people believe that adding a cache can enhance read query performance, and since many popular companies utilize caches, it must be beneficial. While this may be true, it's essential to question whether your system truly needs a cache. Every architectural decision should be based on a specific reason. Well-known companies add caches to their systems because they have genuine needs, such as handling extremely high traffic where scaling traditional databases becomes challenging.

In my opinion, architecture revolves around managing complexity. The core aspect of architecture is solving problems with minimal resources and complexity. Adding a cache undoubtedly introduces complexity to a system. If your system doesn't require a cache, there's no need to blindly follow others. However, understanding why others implement caches and the problems they solve can provide valuable insights into designing your system.

Considering the cache example, the main reason for adding a cache is the improved read performance compared to traditional disk storage. However, the key message conveyed by caches is that scaling the cache component is easier than scaling traditional database storage. Additionally, caches can support higher concurrent traffic in high-traffic systems, thereby facilitating read performance.

In the context of a large traffic system, scaling a traditional database without using cache architecture can be extremely challenging in today's internet environment. Therefore, choosing a cache on top of a traditional database is beneficial because modern cache components support horizontal scaling, making it easier to scale compared to traditional databases like MySQL. While adding a cache introduces complexity, it is considerably less complex than scaling a traditional database.

In summary, software architecture is vital for managing complexity and solving problems efficiently. Understanding the reasons behind architectural decisions, such as adding a cache, helps us make informed choices based on the specific needs and challenges of our system. By evaluating the benefits and trade-offs, we can design systems that perform optimally in high-traffic environments while effectively managing complexity.

Before talking about distributed tracing, we need to understand distributed logging and microservices architecture.

In a monolith application, logs are already centralized somewhere. We can search the logs easily without needing a complex log architecture to process application logs.

When comes to a microservices architecture, logs become more complicated. Imagine we have 100+ microservices and each service has its own logs. How can we search logs from distributed loggings? To solve this, we need a log aggregation layer to aggregate logs from different sources and centralize them.

Now, we centralized the logs but how can we know the sequence of logs and where the logs are from? For example:

• Which service is my caller service?

• Which service is my dependency service?

• Which service is the first service that initiates the request?

• Which service return errors?

• How many services are involved in the call chain?

• …

To solve these issues, we need Distributed Tracing to complement Distributed Logging.

From the diagram, each request contains traceId, parentSpanId, and spanId. The service relationships are connected by using these IDs. For example, we can search traceId=123 to get all the logs and relationships for the request. We can also use other ids to narrow down the debugging scope.

Overall, distributed tracing complements distributed logging by providing additional insights into the interactions and dependencies among microservices. It allows you to trace the flow of a request across different services, understand the sequence of events, and gain visibility into the performance and behavior of each service involved in the request.

How does it facilitate developers’ work?

• Performance analysis: Developers can measure the time spent on each request and identify potential performance bottlenecks or areas for optimization within their microservices architecture.

• Troubleshooting: When an error occurs, distributed tracing helps narrow down the scope of investigation by identifying the exact service responsible for the error. This allows developers to reach out to the respective service owner to address the issue efficiently.

• Service dependencies: Visualizing the service dependencies through distributed tracing enables developers to understand how different microservices interact with each other, facilitating debugging and overall system comprehension.

Writing documentation is almost my day-to-day work as a software engineer. The reason why I write documentation is that good documentation can help my team understand the system better and it is like a knowledge-sharing process. One day if I am on vacation, my teammates can still gain the knowledge that they need from the documentation without asking me.

I know not every engineer likes to create documentation. Some engineers might feel that creating documentation is just wasting time because the system is changing fast. That said, the documentation will be outdated fast. Yes, maintaining documentation is hard, and need to spend resources on that. But, when you work on a large system, good documentation can definitely facilitate team knowledge sharing and avoid some repetitive questions from others. It can help to free yourself from the loop of answering questions.

The more you share, the more extra things you can create. That means when you share your knowledge with others to make them grow, you will save a lot of time. So, if you are working in a large complex system and the team is large, I do think investing in documentation is a good choice for your engineering team.

From my experience in writing documentation, I summarized the following key points for writing good documentation:

1. Know your audience: Understand your audience's knowledge level and the specific needs of your audience. This will help you tailor your documentation to their expectation.

2. Define your message: Clearly determine the core message or purpose of your documentation. What information do you want to deliver? Understanding your message will guide your writing and help you stay focused. If you don’t define your message, sometimes, the content might be too rich and lose focus. With this writing style, your audience might not know what you want to deliver in the documentation. Ask yourself, what message you are trying to deliver when writing documentation.

3. Tell a story: Frame your documentation in a narrative structure that engages readers. Start by presenting a problem and then providing the solution in a logical sequence For example, When documenting a system, introduce the problem, present the high-level architecture, explain critical scenario workflows, and delve into API and database designs. This approach guides readers to understand the system from a big picture to detailed aspects.

4. Provide concise summaries: Instead of providing a lot of raw content to readers, help them summarize the content to give readers a quick overview and provide a link to the detailed content at the end, enabling them to find relevant information efficiently. This approach allows readers to grasp the main points quickly and explore further if desired.

5. Visualize with diagrams: Instead of presenting a large block of content, leverage diagrams, flowcharts, or other visual representations to convey complex information. Visuals make it easier for readers to grasp concepts and understand relationships between different elements.

6. Break down large documentation and create links: If you have extensive documentation, break it down into smaller, more manageable sections. Create separate documents for different topics and establish clear links or cross-references between them. This allows readers to access specific information quickly and navigate between related topics effortlessly.

What else do you think are important elements for good documentation?

Share your thoughts below.

Pub/Sub makes an architecture to be resilient to failures and increases system availability in a high-traffic situation. But, it also brings us several drawbacks. In this article, I will walk you through the potential drawbacks of Pub/Sub architecture.

Applying Pub/Sub architecture to a system might have the following trade-offs:

• Latency

Introducing a Pub/Sub to a system will increase latency. The diagram shows the difference between direct connection and indirect connection. Originally, Service 1 only communicate with Service 2 directly through REST or RPC. After applying Pub/Sub, the request is submitted to Message Broker first, and then wait for Service 2 to consume the messages. This introduces latency to the system and it will be obvious when traffic is high.

• Development Complexity

Before applying Pub/Sub architecture, the development complexity between 2 services is HTTP request where HTTP client is common in any architecture, so we can ignore the complexity. Now, after introducing Pub/Sub to the system, we bring extra complexity to the architecture. Not every developer is familiar with Pub/Sub architecture in-depth. If there are any issues related to the Pub/Sub architecture, does anyone in the team know how to solve them? If not, it will bring unknowns to the architecture.

• DevOps Complexity

Bringing Pub/Sub to the system architecture also increase DevOps complexity. DevOps engineers need to manage the complexity that the Pub/Sub brings to the architecture including creating a cluster and managing topics and partitions. Without knowing the technology in-depth, it is hard to manage the complexity reasonably.

To sum up, Pub/Sub is good but we still need to manage the complexity. By knowing the trade-off, we can make better decisions when creating an architecture. In general, applying Pub/Sub to architecture will bring latency, development complexity, and DevOps complexity to us, apply it wisely and consider the trade-offs to see if the team can pay for it.