Sponsors
- Check out this powerful framework on ABP Framework for .NET. A game-changing platform for building robust, modular, and maintainable applications faster than ever!
Maintaining a codebase is easy, until it’s not…
What begins as a well-structured project can quickly turn into a fragile mess. But it’s not always about poor architecture decisions. More often, it’s the result of subtle coding mistakes, the kind that slip into daily commits and slowly degrade the system’s integrity.
In this two-part series, I’ll cover the 7 most common mistakes that make your codebase fragile. These are patterns I’ve seen across real-world projects, regardless of tech stack or team size.
Fixing them doesn’t require a rewrite, just awareness and discipline…
Let’s start exposing what’s quietly weakening your code.
1 – Magic strings and numbers
Magic values are silent killers. They look harmless at first, just a string or number hardcoded into your method. But as your project grows, they spread across the codebase, making it fragile and harder to change safely.
if (user.Role is "Admin")
{
}
//or
if (discount > 0.15)
{
}
Instead, replace magic values with constants or enums. It improves readability, testability, and reduces the risk of subtle bugs when requirements change.
if (user.Role is Role.Admin)
{
}
//or
if (discount > Constant.DiscountRate)
{
}
This small change makes your code easier to refactor, safer to evolve, and clearer to your team.
2 – Using Comments and Regions
If you need a comment to explain what your code does, your code is the problem.
Developers often fall into the trap of writing code that’s hard to understand, then patching it with a comment instead of fixing the design.
This doesn’t improve maintainability. It just masks poor structure.
// Validates if user can access the dashboard
if (u.R == 1 && !string.IsNullOrWhiteSpace(u.T) && u.A >= DateTime.UtcNow)
{
// ...
}
This line is screaming for a comment because the code is unreadable. But the real fix isn’t a comment, it’s rewriting it with intention:
if (CanAccessDashboard(user))
{
// ...
}
Now it’s self-explanatory. No comment needed.
What about #region?
If you’re adding regions to “organize” a file, you’re likely hiding too much logic in one class:
#region Mapping
// 40+ lines
#endregion
#region Validation
// 60+ lines
#endregion
That’s not structure. That’s a God class in disguise. Split it. Extract in a Mapping class, Validation class, etc.
Note: Comments are OK when you are writing documentation like (e.g. Swagger / XML docs)
3 – Empty Catch blocks
Many developers do this to “prevent the app from crashing,” but what they’re really doing is creating a black hole where critical failures go to die.
try
{
ProcessSomething(customer);
}
catch
{
// ?
}
What just happened? Did the database fail? Was it a null reference? Is the system inconsistent now? You have no idea, and neither will the developer who inherits this code.
This is worse than failing fast. It’s failing silently.
try
{
ProcessSomething(customer);
}
catch (Exception ex)
{
_logger.LogError(ex, CustomerMessage.FailToProcessSomething);
throw;
}
4 – Using Mapping Libraries
Mapping libraries sound great in theory: write less code, map objects automatically, and move faster. In practice, they often introduce more confusion than clarity.
Using mapping libraries like AutoMapper introduces hidden complexity and runtime surprises.
I prefer manual mapping. It’s explicit, testable, better performance, more control, and easy debug. If a mapping breaks, I know exactly where it lives and what caused it. No magic. No hidden conventions. Just code I can read and trust.
public static class CustomerMappingExtensions
{
public static CustomerDto ToDto(this Customer customer)
{
return new CustomerDto
{
Id = customer.Id,
Name = customer.Name,
Email = customer.Email
};
}
}
You don’t waste time hunting down mapping configs scattered across the codebase, you write it once, and it’s crystal clear to anyone reading it, with AI tools today, the verbosity isn’t even a problem anymore.
5 – Not validating your code
Code that assumes everything is fine is code waiting to break.
A method that trusts every input, every dependency, and every state is fragile. It’s not clean. It’s naive.
app.MapPost("/customers", async (
CreateCustomer.Command command, validator,
ISender sender) =>
{
var result = await sender.Send(command);
return result.IsSuccess
? Results.Ok(new { result.Value })
: Results.Problem(
title: "Business rule violation",
detail: result.Error,
statusCode: StatusCodes.Status400BadRequest);
});
You can’t trust what’s coming from the outside, not from APIs, not from frontends, not even from your own database if it’s shared. Nulls, empty strings, unexpected values, expired tokens, they’ll sneak in. And when they do, your system needs to handle them loudly, not die silently.
app.MapPost("/customers", async (
CreateCustomer.Command command,
IValidator<CreateCustomer.Command> validator,
ISender sender) =>
{
var validation = await validator.ValidateAsync(command);
if (!validation.IsValid)
{
var errors = validation.Errors.Select(e => e.ErrorMessage);
// return
}
var result = await sender.Send(command);
return result.IsSuccess
? Results.Ok(new { result.Value })
: Results.Problem(
title: "Business rule violation",
detail: result.Error,
statusCode: StatusCodes.Status400BadRequest);
});
6 – Using Methods and Variables with Confusing Names
Readable code isn’t just about formatting or style. It starts with meaningful names, names that reflect intention, not just implementation. When developers choose names like data, item, doStuff, or handle, they’re not being “generic for reuse.” They’re being lazy.
if(!Validate(selectedFile.Size))
{
//...
}
// Or
var d = await GetCustomerDiscountAsync();
Avoid generic names like Validate() or Check(), Instead, opt for more descriptive names:
if(!IsValidFileSize(selectedFile.Size))
{
//...
}
//or
var customerDiscountPercentage = await GetCustomerDiscountAsync();
7 – Using exceptions for expected cases
If a user sends bad input, or a record isn’t found, that’s not exceptional. That’s expected.
Throwing exceptions in these scenarios doesn’t make your API more robust, it makes it noisy, slower, and harder to test.
if(notice is null)
{
throw new KeyNotFoundException("Notice not found.");
}
Instead, use result pattern to represent failures explicitly, and let exceptions bubble only when something really broke:
if(notice is null)
{
return Result.Failure(Error.NotFound(CResponseMessage.NotFound));
}
Conclusion
The mistakes in this list aren’t theoretical. They show up in real codebases, create real bugs, and cost real time. Most of them come from good intentions: trying to move fast, abstract early, or follow every principle at once.
But clean, maintainable software is built on clarity, not cleverness.
If something breaks, you should know why. If you read a method, it should explain itself. If an error happens, it shouldn’t be a surprise.
This was just Part 1. In the next part, we’ll go deeper into the traps that silently rot your codebase.
Until then, audit your own code. See which of these mistakes are hiding in plain sight.
Thank you for reading.
See you next time!
Sponsors
- Check out this powerful framework on ABP Framework for .NET. A game-changing platform for building robust, modular, and maintainable applications faster than ever!
