iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
💬

Dealing with Bad Code: How Far Should You Go?

に公開

Characteristics of "Shitty Code"

The term "shitty code," which one occasionally encounters in software development, is familiar to many programmers. However, the definition of what actually constitutes shitty code differs depending on the project or the individual developer. In this context, shitty code refers to code with the following characteristics:

  • No comments in the code: Because there are no comments within the code, complex logic or the intent of the code is unclear. This makes it difficult for other developers to understand the code, hindering maintenance and extension.

  • No comments on DB columns: Due to a lack of descriptive comments for database columns, the purpose of each column and the nature of the data are unclear. For example, if a column named "code" simply contains a numeric value, it becomes difficult to determine what that value represents.

  • Unclear code intent: The logic written in the code is opaque, making its purpose and functionality hard to read. This is caused by inappropriate naming conventions, complex logic, or a lack of documentation.

  • Insufficient information in variable names: Because variable names are generic and abstract, it is unclear what they represent. For example, names like data or item do not clarify the use or content of the variable.

  • Broad variable scope: If the range from where a variable is declared to where it is used is too wide, tracking the variable becomes difficult and can cause bugs.

  • Long processes: When functions or methods are excessively long, it becomes difficult to understand, maintain, and test them.

  • Coupled layers: When different layers of an application are tightly coupled, it becomes difficult to test, modify, or reuse each layer independently.

  • Lack of tests: A lack of unit tests or integration tests makes it difficult to guarantee the reliability of the code.

  • Lack of documentation: A lack of documentation for the codebase makes it difficult for new developers to understand the existing code, raising the barrier to entry for the project.

  • Unused DB columns: The presence of unnecessary columns in the database makes it difficult to maintain data integrity and can negatively impact database performance.

  • Massive amounts of copy-pasted code: When the same or similar code is repeated in multiple places, the maintainability of the code decreases, making changes difficult.

  • Overuse of the Object type: Excessive use of the generic Object type leads to a lack of type safety and increases the possibility of runtime errors.

  • Massive amounts of commented-out code: If many pieces of commented-out code remain, it becomes difficult to understand what is active and what is inactive in the current codebase.

In this article, I will introduce how to deal with such shitty code using specific steps. The goal is to improve the codebase in an efficient and practical way to enhance software quality over the long term.

Furthermore, this article focuses on how to coexist with shitty code. It is unrealistic to eradicate all shitty code, and sometimes it is simply too costly. Therefore, we will discuss how to improve shitty code as efficiently as possible while avoiding high-cost solutions. Let's learn how to judge when to push forward and how to wisely coexist with shitty code.

Considerations on Testability

Code that is in a state where tests can be easily written is generally not considered "shitty code." One of the characteristics of high-quality code is ease of testing. Testability implies that the code is well-organized and properly structured, making its behavior easy to understand. Such characteristics are crucial elements for improving maintainability and overall quality. The refactoring methods introduced in this article target shitty code at a level where testing is difficult or impossible.

Coexisting with Shitty Code

In software development, it is almost impossible to be completely free of shitty code. Due to various factors such as project progress, team changes, and technological evolution, there is always room for improvement in the codebase. The key is not to try to eliminate all shitty code, but to find ways to coexist with it efficiently.

Considerations on the Existence of Shitty Code

The fact that a lot of shitty code exists suggests that it has a history of bringing in certain benefits. In many cases, shitty code is born out of short-term goal achievement or rapid market entry. This is often caused by development under business pressures such as tight deadlines, sudden requirement changes, or resource constraints.

In the early stages of a project, prioritizing rapid feature implementation and market entry over writing perfect code may occur. Under such circumstances, the speed of delivery and feature implementation are generally prioritized over code quality and future maintainability. As a result, technical debt accumulates, leading to shitty code that is difficult to maintain or extend in the long run.

However, behind the creation of shitty code is a history where it temporarily achieved business goals and brought profit to the company. Therefore, rather than simply viewing shitty code as evil, it is important to understand it as an inevitable product of balancing business and technology. Based on this understanding, refactoring and paying off technical debt at the right timing become keys to a healthy software development cycle.

The Impracticality of Eliminating All Shitty Code

Attempts to completely eliminate shitty code often consume excessive time and resources. In reality, compromise is necessary. Many factors, such as project priorities, resource availability, and delivery deadlines, influence this decision. Rather than aiming for perfection, it is important to set realistic goals based on the team and project situation.

Exploring Efficient Ways to Coexist

Coexisting with shitty code is achieved through prioritization and selecting efficient approaches. Focus on the most critical issues or the improvements with the greatest impact, and choose methods that yield the maximum effect with the least effort.

Methods for Improving Shitty Code

We will evaluate the methods for improving shitty code using the following three metrics on a five-point scale:

  1. Recommendation Level: The general level of recommendation for implementing this improvement method.
  2. Effort: The labor or time required to implement the improvement method.
  3. Effect: The magnitude of the effect expected as a result of implementing the improvement method.

Each metric is evaluated on a five-point scale as follows:

  • ⭐: Low / Little / Small
  • ⭐⭐: Somewhat Low / Somewhat Little / Somewhat Small
  • ⭐⭐⭐: Average / Average / Average
  • ⭐⭐⭐⭐: Somewhat High / Somewhat Much / Somewhat Large
  • ⭐⭐⭐⭐⭐: High / Much / Large

Based on these evaluation criteria, we will assess the recommendation level, effort, and effect of each improvement method.

1. Adding New Endpoints for Functional Extension

  • Recommendation Level: ⭐⭐⭐⭐

  • Effort: ⭐⭐

  • Effect: ⭐⭐⭐⭐

  • Instead of modifying the existing API directly, extend functionality by adding new endpoints. This allows for the introduction of new features without affecting existing systems or clients.

  • Adding new endpoints enables the expansion of necessary functionality while maintaining the stability of the existing API. This is an effective and low-risk approach, especially when the existing system is widely used.

  • This method provides a flexible and safe solution for meeting new requirements without making major changes to the existing API's codebase.

2. Adding Appropriate Comments

  • Recommendation Level: ⭐⭐⭐

  • Effort: ⭐⭐

  • Effect: ⭐⭐⭐

  • Appropriately add comments to each section within the code to explain its intent and logic. This improves the readability and maintainability of the code.

  • Some developers may oppose adding excessive comments, but this usually refers to well-organized code. For complex and hard-to-read code, appropriate comments help understanding and prevent misunderstandings.

  • Especially in low-quality areas of the code, it is effective to add comments to alert other developers. This is also important to prevent less experienced developers from adopting incorrect coding styles.

3. Splitting Long Functions

  • Recommendation Level: ⭐⭐⭐⭐⭐

  • Effort: ⭐⭐⭐

  • Effect: ⭐⭐⭐⭐⭐

  • By splitting a single long function or complex logic into multiple smaller, more manageable functions, you improve the readability and reusability of the code.

  • Splitting functions makes the code easier to understand and increases the efficiency of testing and debugging. Additionally, it becomes easier to respond to cases where changes or extensions are required.

  • Often, splitting functions may involve initial risks, but from a long-term perspective, it can significantly improve the quality of the codebase. Proper splitting of functions is particularly important from the viewpoints of test creation and maintainability.

4. Mapping Object Types to Classes

  • Recommendation Level: ⭐⭐⭐

  • Effort: ⭐⭐⭐⭐

  • Effect: ⭐⭐⭐⭐

  • Avoid using generic Object types and instead map them to more specific classes to improve the type safety and maintainability of the code.

  • This approach can be time-consuming, but implementing it for frequently used processes will yield the greatest results.

  • Since this change also affects the calling code, careful implementation is required. However, in the long run, it significantly improves code quality and maintainability.

5. Variable Name Refactoring via IDE

  • Recommendation Level: ⭐⭐⭐⭐⭐

  • Effort: ⭐⭐

  • Effect: ⭐⭐⭐⭐

  • Use the refactoring features of an Integrated Development Environment (IDE) to make variable names more appropriate and clear. This significantly improves the readability of the code.

  • Adopting consistent naming conventions makes the code easier to understand and streamlines future maintenance work.

  • Properly named variables improve code readability and make it easier for other developers to understand. This is especially important in team development.

  • If similar variable names are frequently used, consider the approach in "3. Splitting Long Functions".

6. Removing Unnecessary Commented-out Code

  • Recommendation Level: ⭐⭐⭐⭐⭐
  • Effort: ⭐
  • Effect: ⭐⭐⭐
  • It is recommended to quickly delete unnecessary commented-out parts in the code. This reduces the number of lines and decreases the need for scrolling.
  • Deleting commented-out code helps keep the codebase clean and organized. This improves readability and avoids confusion for other developers when they are understanding the code.

7. Proactively Add Comments to DB Columns

  • Recommendation Level: ⭐⭐⭐⭐⭐
  • Effort: ⭐⭐
  • Effect: ⭐⭐⭐⭐
  • Adding comments to database columns clarifies the purpose and role of each column. This makes the database structure easier to understand and helps new developers join the project quickly.
  • Even if the amount of comments increases, database columns are unlike source code in that the volume is rarely an issue. There is no need to worry much about this to increase database transparency.
  • Databases are typically used for a longer period than source code. Therefore, adding useful comments to columns from a long-term perspective is very effective for the maintenance and operation of the database.

Summary

In this article, we focused on the common problem of "shitty code" in software development and explained its characteristics and improvement measures in detail. Our final goal is to improve the quality of the code over the long term. Since it is unrealistic to eliminate all shitty code at once, it is recommended to choose efficient, cost-effective methods that consider effort and effect as a more practical approach. Through such strategies, we can continuously improve software quality and build a better development environment. If you want to feel the impact, I recommend starting with the modifications that require the least effort.

Discussion