Concise Code is Better Code

Sawyer X

·

Follow

3 min read

·

Dec 6, 2023

--

1

Listen

Share

Or: Your “self-documenting code” is terrible

To avoid unreadable code and unnecessary comments, you might write “self-documenting code,” which is far longer and becomes even less understandable. It might make for a “likable” LinkedIn post, but it makes for worse code.

Self-documenting is good. Code comments can also be good. These are not exclusive. However, concise code is best.

Let’s define concise code:

• Short and accurate, doing only what it needs to do.
• Easy to read and follow.
• Performant.
• Not about saving characters, but about eliminating unwarranted complexity.

I avoid calling it “self-documenting code” because often, people use the term to showcase unnecessarily verbose code in the name of “readability.”

Let’s use an example

def process_transaction(user_balance, transaction_amount):
    # Check if the transaction can be processed
    if user_balance >= transaction_amount:
        execute_transaction(transaction_amount)

You write this perfectly fine code, but then a more seasoned (or LinkedIn-trained) developer comes along and says, “That comment is so unnecessary! Let me show you how to eliminate it!” and writes this code instead:

def process_transaction(user_balance, transaction_amount):
    if can_process_transaction(user_balance, transaction_amount):
        execute_transaction(transaction_amount)

def can_process_transaction(user_balance, transaction_amount):
    return user_balance >= transaction_amount

Now we separated the code into another function that checks whether the transaction can be processed (you know, what the condition you wrote already did), and now we run the condition on that new function. Hey, look, no comment!

Why is this worse?

• The original code was short and perfectly readable. The comment didn’t add, but it also didn’t detract.
• We now have an additional function and increased the code from three lines to five.
• We need to read more to understand what’s happening.
  “Can execute transaction? How does it determine that?”
• Additional functions take more memory and CPU: For the function pointer, the variables in the heap, the arguments on the function stack call frame, and the scoping code for memory allocation, and creating and eliminating new arguments and new variables.
• There’s still an “else” condition missing, which many linters would rightfully flag.

Concise

If we wanted to eliminate the comment and make it more readable, instead of increasing the code, we would make it more concise by reversing the condition and returning early:

def process_transaction(user_balance, transaction_amount):
    if user_balance < transaction_amount: return
    execute_transaction(transaction_amount)

This code:

• Has only two statements
• Handles both the true condition (execute transaction) and the false condition (return from the function) without needing to write “if/else”
• Does not need a comment
• Has no extra functions, additional variables, arguments, or function scopes
• Does not have a second or third-level indentation.

(I admit, not all will agree the condition is more readable this way. Code can be highly subjective, and any two developers will have five different opinions.)

Striking the Right Balance

Effective coding is not just about reducing line count; it’s about enhancing clarity and functionality. This means verbosity is sometimes necessary, especially in complex scenarios where additional context, variables, or explanation is beneficial. The same goes for code comments.

Remember, good code is like a well-written book — every word counts and every line should serve a purpose.