Second in a series on practical software design.
Technical details are essential, but they're not the solution
Which is clearer?
Here's a simple user story for a lending library api:
As a library member, I want to borrow a book so that I can take it home.
And here are two code blocks that implement it. Take a few seconds to look at each. Which is easier to understand?
[HttpPost("borrow")]
public async Task<IActionResult> Borrow(int bookId, int memberId)
{
var connectionString = _config.GetConnectionString("LibraryDb");
using var conn = new SqlConnection(connectionString);
await conn.OpenAsync();
var cmd = new SqlCommand("SELECT * FROM Books WHERE Id = @id", conn);
cmd.Parameters.AddWithValue("@id", bookId);
var reader = await cmd.ExecuteReaderAsync();
Book book = null;
if (await reader.ReadAsync())
{
book = new Book();
book.Id = (int)reader["Id"];
book.Title = reader["Title"].ToString();
book.DueDate = reader["DueDate"] as DateTime?;
book.CheckedOutByMemberId = reader["CheckedOutByMemberId"] as int?;
}
reader.Close();
if (book == null)
{
return NotFound();
}
// check if already checked out
if (book.CheckedOutByMemberId != null && book.CheckedOutByMemberId != 0)
{
return BadRequest("already out");
}
// now get the member fines
decimal fines = 0;
var cmd2 = new SqlCommand("SELECT Amount FROM Fines WHERE MemberId = @m AND Paid = 0", conn);
cmd2.Parameters.AddWithValue("@m", memberId);
var reader2 = await cmd2.ExecuteReaderAsync();
while (await reader2.ReadAsync())
{
fines = fines + (decimal)reader2["Amount"];
}
reader2.Close();
if (fines > 0)
{
return BadRequest("has fines of " + fines.ToString());
}
// set due date to 2 weeks from now
var due = DateTime.Now.AddDays(14);
var cmd3 = new SqlCommand("UPDATE Books SET DueDate = @d, CheckedOutByMemberId = @m WHERE Id = @id", conn);
cmd3.Parameters.AddWithValue("@d", due);
cmd3.Parameters.AddWithValue("@m", memberId);
cmd3.Parameters.AddWithValue("@id", bookId);
await cmd3.ExecuteNonQueryAsync();
// add to member checkout list
var cmd4 = new SqlCommand("INSERT INTO MemberCheckouts (MemberId, BookId, CheckedOutOn) VALUES (@m, @b, @now)", conn);
cmd4.Parameters.AddWithValue("@m", memberId);
cmd4.Parameters.AddWithValue("@b", bookId);
cmd4.Parameters.AddWithValue("@now", DateTime.Now);
await cmd4.ExecuteNonQueryAsync();
return Ok("borrowed");
}
[HttpPost("borrow")]
public async Task<IActionResult> Borrow(int bookId, int memberId)
{
var book = await _books.GetById(bookId);
if (book is null) return NotFound();
if (book.IsCheckedOut)
return Conflict("Book is already checked out.");
if (await _members.HasOutstandingFines(memberId))
return BadRequest("Outstanding fines must be cleared before borrowing.");
book.SetDueDate(_clock.Now.AddDays(LoanPeriodDays));
await _bookCheckoutService.CheckOutBook(memberId, book);
return Ok();
}
If you're like me, you chose the second. Why? It's easier to parse because there's less information in it (also, it uses more intuitive variable and method names, but that's for another post). We have a limited capacity for detail, and usually only want enough to answer the question in front of us. Past that point, our capacity for analysis and critical thinking deteriorates. Less information in this case is always better.
The Case Against Detail
The second method is clearer because it abstracts the technical details that are in the first. The terms "abstracting" and "abstraction" are omnipresent in design literature: DDD, Clean Architecture, SOLID, etc., all assume you’re comfortable with it, but none of them describe how it works or how to get fluent in it. And despite being foundational, it's — in a future post. For now, the point is this: once you start thinking in abstractions, you stop solving every problem from scratch. It's Legos vs a jigsaw puzzle.
Next Steps
The prose-first approach is a starting point — a thinking tool for breaking out of the detail-first habit and working at the right altitude. In upcoming posts I'll discuss how to use abstraction to identify responsibilities, assign them to objects and incrementally build a working design. But none of that is possible until you can see the forest first.
SOCIAL SHARE CARD GENERATOR