DEV Community: David Adamo Jr.

Texas Sharpshooters and Test-Driven Development (TDD)

David Adamo Jr. — Fri, 09 Feb 2024 02:49:52 +0000

Cover image taken from an illustration by Dirk-Jan Hoek

I recently learned about a logical fallacy called The Texas Sharpshooter fallacy. The first thought that crossed my mind when I first read about it was, "What does Texas have to do with any of this?". I still don't have a convincing answer for that one.

More importantly, the second thought that crossed my mind was how The Texas Sharpshooter fallacy clearly expresses one of the ways I think about Test-Driven Development (TDD). This blog post describes how TDD may reduce your likelihood of writing tests like a Texas Sharpshooter.

So what is this Texas Sharpshooter fallacy anyway?

The Texas Sharpshooter Fallacy

The Texas Sharpshooter Fallacy occurs when you find patterns to fit something you've already assumed to be true or correct. The name comes from an analogy where a shooter fires shots at a barn door and then paints targets around the bullet holes to create the false impression of being an excellent marksman.

Test-Driven Development (TDD)

TDD is a software development approach that encourages you to write tests before writing the code that makes the tests pass. It revolves around a red-green-refactor cycle that comprises the following steps:

Write a test that fails (red)
Write the minimal amount of code that makes the test pass (green)
Refactor the code to meet quality standards while ensuring that tests still pass.

TDD has several benefits. One often touted benefit of TDD is that it helps you make better design decisions. Since TDD demands that you write tests first before writing the corresponding code, it forces you to always start by thinking through the design and expected behavior of the code you're going to write. This upfront focus on design and behavior often results in better software design and architecture relative to a test-after approach where you dive straight into writing code before writing corresponding tests.

What does the Texas Sharpshooter Fallacy have to do with TDD?

The positive influence that TDD can have on software design is generally well-known. A less popular discussion is the direct positive influence that TDD could have on your tests. Remember that tests should verify that your code behaves the way it is supposed to, as defined by software requirements. Sometimes, you may end up writing code that seems acceptable to you without realizing that there is some difference between what your code does and what it is supposed to do. When you write code before writing tests, you are more likely to write tests that verify what the code does instead of what it is supposed to do. Writing code before tests makes it too easy for you to mold your tests around flawed code without realizing it. In many cases, you'll end up with tests that merely confirm flawed behavior.

TDD forces you to start by writing a failing test based on the expected behavior of the code you'll eventually write. Note that the code that the failing test seeks to verify does not exist at this point, so you are primarily focused on the expected behavior, and there is nothing around which to (incorrectly) mold your tests. In other words, your tests written as part of the TDD cycle are much less likely to be biased by code you've already written because the code does not exist yet.

In the context of the Texas Sharpshooter analogy, your code represents the shots you've fired at the barn door, and your tests are the targets that those shots are meant to hit. Writing your code before writing your tests is like firing shots at the barn door before painting the targets. When you write your code first (i.e., fire shots) and then write the tests afterward (i.e, paint targets), it is too easy to start writing tests that are influenced ONLY by the current behavior of the code you've just written, even when that behavior is not what you intended or what the software requirements demand. If you are not careful, writing tests after writing your code will turn you into a "Texas Sharpshooter". And it's going to feel great. After all, your shots will almost always hit the target when you shoot first and paint targets around the bullet holes afterward.

Many software developers (including me) tend to write tests after writing implementation code but do not always realize that they are sharpshooters painting targets around problematic code. TDD encourages you to write tests BEFORE writing the code that makes the tests pass. Therefore, if you want to avoid being a "sharpshooter", try TDD.

Avoid Fakers in Unit Tests

David Adamo Jr. — Thu, 08 Feb 2024 04:03:02 +0000

In your unit and integration tests, avoid using tools that automatically generate test input data. Unless you are fuzz testing or your goal is to create property-based tests, these test data generators (a.k.a. fakers) are likely to do more harm than good in the long run because:

Your tests will become much slower than they should be. The computational cost of randomization and data generation adds up much quicker than you might think. Slow tests are productivity poison.
By using fakers in your tests, you increase the likelihood of flakiness due to randomized data. Your future self will have a tough time figuring out why a specific test failed. Tests should be repeatable and deterministic, with input values that stay the same each time you execute them.

It is often better to explicitly specify your test inputs. If you have to use a faker in your tests, make sure it always generates the same test inputs each time your tests are executed. You can do this by configuring your faker with a random seed.

Duplication over Abstraction in Unit Tests

David Adamo Jr. — Sun, 26 Feb 2023 19:09:17 +0000

One of the first things you learn as a software engineer is to avoid code duplication whenever possible. But this same learned aversion to duplication is what causes many software engineers to fill their unit tests with logic and abstractions that cause the tests to become unreliable.

On a scale from duplication to abstraction, your code and its corresponding unit tests should almost never be on the same level. Unit tests are not the place for clever logic, abstractions, and code reuse. Logic and abstractions eventually cause your unit tests to become fragile and difficult to understand. If you're starting to feel like your unit tests need unit tests, then you're probably doing it wrong.

In your production code, it often makes sense to treat duplication like an enemy to be vanquished everywhere it rears its ugly head. But you're much better off treating duplication like a friend in your unit tests. In other words, while you favor abstraction over duplication in your code, you should simultaneously favor duplication over abstraction in your unit tests.

What does bad code look like?

David Adamo Jr. — Mon, 30 Jan 2023 18:40:21 +0000

What does bad code look like? Well, code that does not do what it should is probably bad by default. Not much else to say about this one.

Beyond that, it is probably easier and more interesting to think of bad code in terms of what it feels like. Most of the bad code I've seen tends to fall into one of three categories.

Easy to understand, difficult to change

Working with this kind of code initially feels pleasant, but could quickly devolve into a terrifying and never-ending game of Jenga. Code like this is common among new programmers and could actually be useful in some contexts. In search of growth and perfection, too many software engineers eventually lose their tactical ability to write this kind of "bad" code.

Difficult to understand, but easy to change once you get around to understanding it

Working with this kind of code feels like a constantly swirling mix of confusion, surprise, and sudden enlightenment. This kind of code is common among experienced software engineers who have their heads full of useful principles, design patterns, and other "best practices". I've had to fight my way out of writing this kind of code more times than I can count.

Difficult to understand, difficult to change

This is just the worst! Avoid like the plague.

This kind of code feels like a terrifying nightmare that continues when you wake up and when you go back to sleep. I'm not sure how one ends up here, but this is certainly not what you want your code to feel like for anyone who touches it.

You'll probably end up with this kind of code when you apply design patterns, design principles, programming paradigms, and/or complex architectures without understanding why these things exist and when to use them.

One of the most elusive aspects of your job as a software engineer is to figure out how to produce code that is both easy to change and easy to understand. Producing such code is not easy, but it is typically the best way to build software that retains its value over time.

Are your Tests Necessary and Useful?

David Adamo Jr. — Wed, 25 May 2022 06:05:20 +0000

Some automated tests are unnecessary or problematic.

For each automated test you write, ask yourself:

Does this test offer any additional test coverage that is not already addressed by some other existing test?
Which defect(s) do I expect this test to find or prevent?
When this test fails, would I be able to easily determine what went wrong based on the test execution report?
Can I reduce the scope of this test so that it integrates fewer components during its execution?
Am I testing a private method directly? If so, can I modify my test or refactor my code and test through a public method instead?

Each test should exist for a good reason, and not merely to tick a box in a checklist. The effectiveness of your testing is dictated primarily by the quality of the tests you have. The number of tests that you do or do not have matters much less than you think.

4 Job Search Tips for New Software Engineers

David Adamo Jr. — Wed, 25 May 2022 06:02:10 +0000

Entering the job market as a new Software Engineer can be challenging. Here are some job search tips for new software engineers.

Take LinkedIn Seriously

Fill out your LinkedIn profile as best you can.

I have applied directly to many jobs outside of LinkedIn. However, all the jobs I have received and accepted so far, except one, originated from my LinkedIn profile.

Avoid Consulting Companies

For your first job, avoid consulting companies if you can. Get a job at a company that is building and selling its own software products.

Many consulting companies move people between customer projects frequently. This project instability often creates an unfavorable environment for mentorship and skill/career growth.

Consider Lesser-Known Companies

Do not limit your job search to well-known multinational companies.

Many lesser-known software companies do great software engineering work and provide fair compensation. Be on the lookout for these hidden gems.

Learn Python

Learn Python, particularly for coding interviews.

Many interviewers understand Python’s relatively simple syntax. With Python, you can get more done in less time and with fewer keystrokes compared to programming languages like Java and C/C++. The time savings add up quickly in a coding interview.

There are many more useful tips that may improve your job search experience. However, the four tips in this post are some important things to consider as you begin your job search.

Code Review Checklist: 62 Things to Look Out For in Code Reviews

David Adamo Jr. — Wed, 23 Feb 2022 14:35:27 +0000

What do you look out for in your code reviews? Is the quality of your code reviews consistent? Do you use a code review checklist?

There are several reasons why the quality and thoroughness of code reviews may vary significantly across pull requests. Some reasons for inconsistency in code reviews include:

The skill and competence level of the code reviewer.
How much the code reviewer knows about the specific issue(s) addressed in the code change.
The time of day when the code review was performed.
The specific programming issues that have been on the reviewer's mind lately.
The reviewer's perception of the code contributor's competence.
The programming languages and technologies used in the code change.

A code review checklist is a useful way to improve the quality and consistency of code reviews. Consistent use of checklists decreases the likelihood that a reviewer's focus is skewed toward specific areas of interest or convenience at the expense of other important areas.

Dr. Michaela Greiler has done some remarkable work on helping software engineers improve their code reviews. This post presents a checklist, based on Dr. Greiler's work, with 62 things to look out for in code reviews. The questions in this checklist are structured such that each question can be answered with either a YES, NO, or Not Applicable (N/A). In theory, the likelihood that a code change is of acceptable quality is inversely proportional to the number of “NO” answers to the questions in the checklist. Many of the questions in this checklist are subjective and almost completely at the discretion of the code reviewer.

Code Review Checklist

PR Etiquette

Does this code change address a single high-level concern?
Are the commit messages clear and well-written?

Implementation

Does this code change do what it is supposed to do?
Is there a simpler alternative to this code change?
Are all the new compile-time and run-time dependencies in this code change necessary and appropriate?
Does this code change use appropriate frameworks, APIs, libraries, and services instead of custom code whenever possible?
Is this code change at the right level of abstraction?
Is the code modular enough?
Does this code change use existing code whenever possible instead of introducing new code?
If this code change does not use similar existing functionality in the codebase, is there a good reason why?
Does this code change use best practices, design patterns or language-specific patterns in ways that improve code maintainability, readability, performance, and security?
Does this code appropriately follow Object-Oriented Analysis and Design principles?
Do all classes, methods, and functions have a reasonable number of lines?
Does this code change add clear value and avoid feature creep?
Does this code change adhere to the idioms and code patterns of the programming language?

Logic Errors and Bugs

Does this code change behave as intended for all use cases you can think of?
Does this code change properly handle unconventional inputs and external events without breaking?

Error Handling and Logging

Does this code change handle errors correctly?
Are error messages descriptive and user-friendly?
Does this code change produce proper logs and debugging information?
Are log messages written in a way that enables easy debugging?
Does this code change ensure that logs do not expose too much technical information that could lead to a security issue?

Usability and Accessibility

Is the proposed solution well designed from a usability perspective?
Does the proposed solution adequately address accessibility concerns?
Are the APIs defined in this code change well documented?

Ethics and Morality

Does this code change use data in a way that minimizes or eliminates privacy concerns?
If this code change adds or alters ways in which people interact with each other, are appropriate measures in place to prevent/limit/report harassment or abuse?
Does this code change adequately avoid exploitation of behavioral patterns or human weaknesses?
Does this code change adequately ensure that it does not cause mental or physical harm to users?
Does this code change adequately ensure that it does not exclude certain groups of people or users?
Does this code change adequately avoid introducing any algorithm, AI or machine learning bias?
Does this code change adequately avoid introducing any gender/racial/political/religious/ableist bias?

Testing and Testability

Is the code well designed from a testability perspective?
Does the code change have enough automated unit, integration, and system tests? If not, do the existing tests adequately cover the code change?
Do the test cases in the code change cover all important inputs or edge cases you can think of?
Are the tests well isolated and independent from one another?

Dependencies

Have necessary updates been made to other artifacts related to this code change (e.g. documentation, configuration, README files, etc.)?
Does this code change adequately consider and address any undesirable effects on other parts of the system?

Security and Data Privacy

Have all new dependencies been audited for security vulnerabilities?
Does this code change appropriately handle authentication and authorization?
Is sensitive information like user data and credit card information securely handled and stored?
Does this code change use appropriate encryption schemes when necessary?
Does this code change properly hide secret information like keys, usernames, and passwords?
Does this code change properly address security vulnerabilities such as cross-site scripting and SQL injection? Does this code change properly sanitize and validate user input?
Does this code change properly validate data retrieved from external APIs or libraries?

Performance, Reliability, and Scalability

Is this code change unlikely to have a significant negative impact on system performance?
Does this code change include all the useful performance optimizations that you can think of?
Does this code change have instrumentation for metrics reporting and failure alerts?
Does this code change use appropriate built-in functions wherever possible?
Has all debugging code been removed from this code change?
Are all performance optimizations in this code change necessary?
Does this code change use some form of caching whenever appropriate?

Readability

Is the code easy to understand?
Are methods and functions small enough to be easily readable?
Are function, method and variable names meaningful?
Are modules located in appropriate and meaningfully named files, folders, and packages?
Is control flow in modules, functions, and methods intuitive?
Is the data flow in modules, functions, and methods intuitive?
Are all comments in this code change necessary and meaningful?
Do the comments in this code change describe why and not what?
Does this project use a linter?

Secondary Review

If this code change impacts different teams, has it been reviewed by people from the affected teams?

This code review checklist is also available as a spreadsheet to edit and improve as you please.

17 Things to Know Before Deciding to Get a Ph.D. in Computer Science

David Adamo Jr. — Mon, 21 Feb 2022 19:11:33 +0000

This post is long overdue and marks the start of a series of blog posts about my journey through earning a Ph.D. in Computer Science.

On August 15, 2012, I moved to the United States of America to accept an offer of admission to a Computer Science Ph.D. program. The decision to pursue a Ph.D. in Computer Science marked the beginning of an arduous five-and-a-half-year journey of self-discovery and personal development. I eventually graduated in December 2017 and it has taken me a few years to settle into life outside of graduate school. 8 peer-reviewed publications, 7 patents, and 4 full-time software engineering jobs later, I now have enough mental clarity to reflect on my time in graduate school and share what I wish I knew at the start of the Ph.D. journey.

Please note that the lessons shared in this post are colored by my particular experience in a Software Engineering-focused research area and at a specific university in the United States. Some of the things mentioned in this post may not apply to all countries, fields of study, and across all universities. Now, without further ado, here are 17 lessons learned in retrospect and things I wish I knew when I started the Ph.D. journey.

It takes a village to earn a Ph.D.
Choose your advisor(s) wisely and carefully.
Be mindful of academic politics.
Avoid resource-intensive research areas.
Software development skill matters much less than you think.
Experiment design skill is more valuable than you think.
Write often and publish early.
You don't write as well as you think.
Grades matter less than you think.
Stay funded.
There is an alarming disconnect between academia and industry practice.
Teaching is difficult but sometimes rewarding.
The non-research career opportunity cost is real and often incredibly high.
Squash impostor syndrome often and early.
Professors are human too.
There are potential immigration advantages.
Do not get a Ph.D. 😊

In subsequent posts, I will elaborate on each of these lessons. Each person's experience in a Computer Science Ph.D. program is unique, and one person's experience is not necessarily a reliable predictor of another's. Having said that, I hope that my experience and perspective on these topics will help people who may be considering a foray into the Ph.D. grind(pdf book).

Managing Simultaneous Learning and Productivity in Software Development

David Adamo Jr. — Mon, 21 Feb 2022 18:55:55 +0000

The abundance of opportunities to learn new things is one of my favorite aspects of being a Software Developer. However, software development in professional settings is often severely time-constrained, so I rarely find enough time to gain an expert-level understanding of the numerous concepts I encounter during the course of my work. These time constraints typically affect how deeply I am able to absorb new technical concepts and still maintain high levels of productivity. Whenever I am faced with a situation that calls for balancing time, learning, and action, my inclination is to formulate and apply some sort of structure to the situation. This post describes the framework I use to manage the simultaneous productivity and meaningful learning in time-constrained contexts.

I like to think about the learning process as a series of questions and knowledge levels:

Level 0: What is it called?
Level 1: What does it do?
Level 2: What are some alternatives and why does this one exist?
Level 3: How does it work/How does it do what it does?

I often use this framework to calibrate how deeply I need to understand new technical concepts within the context of a specific task and associated time constraints. I consider levels 0 and 1 to be “shallow” understanding. Level 2 is neither shallow nor deep, but often sufficient to satisfy my curiosity and help me make more informed choices. Level 3 represents deep understanding. This learning framework may be generalizable to other subject areas and professions, although I use it most often within the context of software development.

Now let us work through a scenario where this framework may be useful. Consider the function below (written in Python):

def first_n_numbers(n):
    num = 0
    while num < n:
        yield num
        num += 1

The first time I saw a Python function like the one above, the yield statement seemed rather strange to me. What thought process did I follow to learn more about this strange yield statement? You guessed it!

Level 0: What is it called?

This level of understanding focuses on concepts and terminology. I consider this to be the most fundamental level of understanding one can achieve about a given subject. Knowing the proper terminology that applies to a particular subject of interest is an invaluable foundation for seeking further information.

In the context of our example with the Python function and yield statement, a quick google search for the phrase “python yield statement” tells me that this construct is called a “generator function”, and is related to iterables, iterators, and loops in Python. If I am really in a hurry and the nature of my task allows, I may keep all these related terms in mind for later, stop at this level of inquiry, and move on with the task. More often than not, I will proceed to level 1 to gain a better understanding of what these “generator functions” do.

In some scenarios, one may already know the right terminology for the subject of interest. For example, if I were reading an article or a book on functional programming and came across the word combinator, it would be rather obvious what exact term I need to search for to acquire additional information. In such a scenario where the precise name of a concept is obvious, I’ll immediately begin further learning at level 1.

Level 1: What does it do?

This level focuses on understanding the immediate effect(s) of using or adopting a particular tool, concept, or programming construct. I typically stop at this level when my top priority is to complete a task, rather than to gain a deep understanding of the particular subject of interest.

In our generator function example, this level of understanding focuses on figuring out what generator functions do when you use them. A little digging on the interwebs tells me that:

A generator function i.e. a function with a yield statement, acts like an iterator. Therefore, such a function can be used as part of a for loop as in for i in first_n_numbers(10).
The yield statement in a function provides a result to the caller without destroying local variables.
Each call to a generator function resumes execution from where it left off after the most recent call.
Generators produce iterables, but they are not collections and thus have no length.

For programming constructs, it is often helpful to find a few code examples at this level to help illustrate proper syntax and semantics.

Level 2: What are some alternatives and why does this one exist?

This is where learning starts to go beneath the surface. This level focuses on identifying alternative ways to achieve the same or similar objectives, and understanding how the subject of interest compares to the identified alternatives. Knowledge acquired at this level helps me to make informed decisions regarding when to apply the subject of interest or choose some other alternative that might be less elegant but more widely understood.

So what are some alternatives to using generator functions as defined in our example? At this level, I will discover that instead of using a generator function with a yield statement, we could:

Write a function that constructs and returns a list in memory.
Create a class with the generator pattern and use an instance of the class as an iterator.

So why would one choose to use a generator function instead of one of the other alternatives outlined above? If the objective is to produce something that can be iterated over, why not just construct a regular Python list, return the newly constructed list and be done with it? It is at this level that I will discover that:

Writing a function that constructs the full list in memory does not scale well. If each item in the list happens to take up a lot of space, or we need to generate a stupendously large number of items, we could run out of memory real quick.
Creating a class with the generator pattern helps us deal with the performance issue, but it involves quite a bit of boilerplate code and convoluted logic relative to using a generator function. The boilerplate becomes more of an annoyance if we have to create many such classes with the generator pattern.
Generator functions are a convenient shortcut to building iterators that are memory-efficient with clear natural logic and without annoying boilerplate code.

With this level of knowledge, I am able to understand when it is beneficial to use a generator function with a yield statement and when it is not. I might choose to use a simple list or some other simple iterable, rather than blindly use a generator. A simple iterable in memory would be a reasonable choice in scenarios where I have a small constrained list of items and do not need to worry about memory and performance.

Ultimately, I have found the knowledge gained at this level to be incredibly valuable for communicating with others and explaining the rationale behind my decisions. Communication and informed decision making is a key ingredient in successful engineering teams. This level of understanding could help foster useful conversations, particularly in code reviews.

Level 3: How does it work/How does it do what it does?

I consider this to be the deepest level of understanding in my framework, assuming the other levels have been sufficiently explored. I typically resort to this level when my primary goal is to teach a class or write technical documentation about a given topic. Most of the time, I do not reach this level of understanding, as the time and effort required often outweigh the immediate benefits. This level is potentially infinite and requires an understanding of how things work at a level beyond what most situations require. For technical concepts in software engineering, many universities spend a significant amount of time teaching concepts at this level and things can get quite arcane pretty fast.

For generator functions, it is at this level that I will seek to understand all of the following:

Python interpreter internals
Python bytecode
Stack frames
Heap memory

I have not yet taken the time to fully understand generators at this level as I imagine it is going to require quite a bit of time and dedication to learn all the other associated concepts that make generators work the way they do. For anyone interested in understanding generators at this level, the “How Python Generators Work” section of this AOSA book chapter might help. Good luck, and have some Ibuprofen or Tylenol close by just in case you get a headache. :)

In this post, I have outlined the framework I use when I need to balance the tradeoff between learning new technical concepts and rapid progress toward the completion of a software development task. I use this framework to calibrate how deeply I need to understand new technical concepts in time-constrained situations that require simultaneous productivity and learning. This is a daily reality for me as a professional Software Developer. I hope others find it useful, enlightening, or at least amusing.