DEV Community: Frank Riccobono

How do you Parse a Tournament?

Frank Riccobono — Tue, 16 Jun 2026 00:00:00 +0000

This article is a continuation of my series on how I created the certificate generator for our local speech and debate league.

Alistair Cockburn describes the “walking skeleton” of your system as “a minimal implementation of a system that is functional from end to end”. He suggests you write that first and then expand to cover the edge cases.

In the previous article, I mentioned that it is possible to export results from the tournament management software (Tabroom) as comma-separated value (CSV) text files. In this next part, I’ll talk about how I addressed our core use case by converting those CSV results files into the data model used to render the certificates. Then I’ll start examining how the parser has evolved to address new use cases I didn’t envision in the first few commits.

Interpreting Results

In a competitive speech tournament, students compete in one of several speaking events. In each event, groups of five to seven students give short performances in front of a judge, who then ranks the competitors according to objective and subjective criteria. Tournaments usually consist of multiple preliminary rounds where students are randomly paired against each other. Students’ final placements are determined by adding up the ranks from each prelim round and applying a tournament-specific set of tiebreakers. At the end of the tournament, we can get the final results for each event in a format like this.

Ranking,Code,Name 1,School,Ranks in Prelims,Reciprocals in Prelims, Points in Prelims
1,"807","John Smith","Some Academy",4.00,2.50,286
2,"804","Jane Doe","P.S. 1337",5.00,2.33,278  
3,"802","Mary Mack","Williams Prep",6.00,2.25,278

The first three columns are fairly generic. The remaining columns will depend on what set of tiebreakers we decide to use.

Ranking is the student’s overall placement. In this example, John Smith was ranked first overall, Jane was second, and Mary was third.
Code is a unique identifier for each entry in the event. We use this to preserve some anonymity while the tournament is in progress.
Name 1 is the student’s full name. You may wonder why it’s Name 1 instead of Name. We’ll get back to that later.
School is the school this student is affiliated with. We are an academic competition, and each student is part of a school team.

The full data model consists of several entities. In short, a Tournament consists of one or more Events. Each Event would conclude with one or more Results. Each Result is attributed to the School that the entry attends. The initial structure of the Result entity is below. It’s a direct translation of the first four columns in the CSV, plus an auto-incrementing primary key.

@Entity
public class Result {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    long id;
    int place;
    String code;
    String name;
    School school; // foreign key reference

    // getters and setters omitted for brevity
}

Aside: How to Parse CSV

Now that we have sample data, we can consider how to extract it from the file. CSV is a deceptively simple format. Many developers might instinctively reach for the naive approach: read the file line by line and split each line by commas. Some of the fields are wrapped in quotes, so those could be stripped out.

import module java.base;

class ReadFile {
    public static void main(String args[]) {
        try (BufferedReader src = Files.newBufferedReader(
            Paths.get("/path/to/file.csv"),
            StandardCharsets.UTF_8);){
            String line = src.readLine();
            String[] columns = line.split(",");
            String rank = columns[0];
            String name = columns[2].replace("\"","");
            String school = columns[3];
            // do something with the results
        } catch (IOException ioe) {
            // do something to recover from the error
            ioe.printStackTrace();
        }
    }
}

In very simple cases, this may seem to work, but it breaks down fairly quickly. Consider what happens when the column value contains a comma. For example, we had two schools in our league known as “Convent of the Sacred Heart, NYC” and “Convent of the Sacred Heart, Greenwich”. If we chop off the part of these names after the comma, we will certainly cause some confusion.

Aside from nested commas, the use of column position is also a limitation of this approach. The header row contains important semantic information about each column, but if we are just splitting strings, we discard that information and become tightly coupled to the order of information in the file. Since we don’t control the producer of the CSV file, we can’t guarantee every column will always have the same order. I already mentioned that the last few columns will almost certainly differ from one tournament to another. Even if we do control the output order, it means that any new columns we introduce in the future must always be appended to the end to avoid incompatibility.

A better approach is to use a proper CSV parser. For this project, I chose Apache Commons CSV because I had already used it on a prior project. Parsing with this library looks like this:

CSVFormat CSV_FORMAT = CSVFormat.Builder
      .create(CSVFormat.DEFAULT)
      .setHeader()
      .setSkipHeaderRecord(true)
      .setAllowMissingColumnNames(true)
      .get();

CSVParser parse = CSV_FORMAT.parse(inputStream);

for (CSVRecord record : parse.getRecords()) {
    String ranking = record.get("Ranking");
    String name = record.get("Name 1");
    // ...etc
}

The DEFAULT format assumes a comma (,) is the delimiter, a double quote (") is used to surround values that might contain the delimiter, and Windows-style line endings (\r\n) are used to separate rows. The last three directives instruct the parser to interpret the first row as named headers, allowing you to access values by name rather than by index.

One limitation, though, is that the CSVRecord class only returns string values, so I also needed to use Integer.parseInt(record.get("Ranking")) to get the numeric value for place.

What’s in a `Name 1`?

Back in 2020, I hadn’t read any Cockburn, but I had built a decent walking skeleton all the same. The first iteration of the software successfully processed all the results from our first speech tournament and generated certificates without issue, but it promptly fell over after our second tournament a week later.

I mentioned students can compete in multiple events, each of which has a somewhat different format. Our second tournament of the year was the first one that season to offer an event called Duo Interpretation. In this event, as the name suggests, teams of two students perform a short acting piece together. When it came time to ingest the results of this event, I noticed that the certificates only displayed the names of one of the two team members.

It turned out that in partner events, Name 1 would contain the name of one partner, and a new column, Name 2, would contain the other partner’s name. Because I was already using column names rather than indexes, the fix was localized.

List<String> headers = parse.getHeaderNames();

if (headers.contains("Name 2")) {
    result.name = csvRecord.get("Name 1") + " & " + csvRecord.get("Name 2");
} else {
     result.name = csvRecord.get("Name 1");
}

Note that, as a secondary benefit of referencing columns by name instead of index, it didn’t matter that sometimes there was another column between Name 1 and School. Without this, we would have seen even stranger results, such as a certificate rewarding John Smith from the school of Jane Doe.

When is a Place not a Place?

My troubles did not end there. Even though we use various tiebreakers, there are still sometimes unbreakable ties. When all is said and done, two students or teams might have received exactly the same ranks throughout the day. What I learned from this tournament was that when an unbreakable tie happens, the Ranking column in the results export indicates this with a prefix. For example, if students were tied for second place, they would both be ranked as “T-2”. When this “T-2” value appeared in a result for the first time, my naive Integer.parseInt(ranking) failed with a NumberFormatException. I had assumed Ranking was a numeric field, but the export treated it as richer information that encoded both the placement and whether that placement was tied.

The tactical fix for this was:

result.place = Integer.parseInt(
    csvRecord.get("Ranking").replace("T-", ""));

Is That Your Final Answer?

Unfortunately, this tournament was not done teaching me lessons. In larger events, we held a final round wherein the top 6 to 8 students competed against each other for final placement. However, in the smaller events, we did not hold a final round. Instead, we calculated the final places based purely on preliminary round scores. When we got the results, I learned that some of the columns had completely different names when exporting the results from an event that did not have a final round versus one that did. For example, in some cases Ranking was Place. In other cases, there was neither a Name 1 nor Name 2 column, but rather an already combined Name field.

This variability led me to introduce a utility method to return the value for the first matching column name.

 String getOrAlternateColumn(CSVRecord csvRecord, String... names) {
    for (String name : names) {
        if(csvRecord.isMapped(name)){
            return csvRecord.get(name);
        }
    }
    throw new IllegalArgumentException("Could not find any of " +
        Arrays.toString(names));
}

Conclusion

I mentioned that CSV is a deceptively simple format. Definitely don’t parse it with string splitting, but, even if you do have column names, they may not guarantee a stable contract. In the end, the hardest part of this project wasn’t parsing the file, but understanding the assumptions behind the data. What seemed like an easy challenge from a bird’s-eye view ultimately exposed the need to handle several data quirks and special cases.

Thankfully, because this logic was encapsulated in the parser, I was able to make these changes on the fly while limiting most of the complexity to the application boundary. The parser needed to evolve, but the internal data model remained stable.

But What About the Trophies?

Frank Riccobono — Sat, 25 Apr 2026 00:00:00 +0000

Backstory

It was the fall of 2020. A new school year had just started, but amidst the continuing pandemic safety measures, we in the speech and debate community were wondering whether we would be able to continue the activity in some form or another. Thanks to a video platform developed that summer by the National Speech and Debate Association, we were fairly confident we could hold virtual tournaments, but we had another practical issue: how would we recognize the winners?

Speech and debate is primarily an educational activity. We don’t encourage students to participate for the trophies, but at the same time, doing well at a tournament is difficult. We still wanted to reward these students for their success. Trophies were the league’s largest expense when running in-person tournaments, and mailing them out after virtual tournaments would have been prohibitive.

Our league director came to me with an idea: certificates. More specifically, we needed a way to generate hundreds of printable certificates automatically, personalize them, and distribute them digitally. Here’s how I did it.

Layout

Maybe I was just biased from years of working in web development, but when I looked at the sample certificates we had printed, I saw a familiar box model.

The layout was primarily centered text with some borders and spacing. I decided to use HTML and CSS. A certificate can be represented as just a few lines of text and markup. The structure was straightforward.

<div class="certificate_border gold finalist">
    <div class="certificate_body placement_certificate">
        <img alt="The tournament logo" src="/nycfl-logo.svg" height="100px"/>
        <p class="nycfl">New York Catholic Forensic League</p>
        <p class="award_certificate">Award Certificate</p>
        <div class="tournament_details">
            <p class="host">Regis High School</p>
            <p class="tournament_name">NYCFL First Regis</p>
            <p class="tournament_date">September 26, 2020</p>
        </div>        
        <p class="place">First Place</p>
        <p class="before_text">This certificate is given to</p>
        <p class="name">Jane Doe</p>
        <p></p>
        <p class="before_text">to recognize outstanding performance in the category of</p>
        <p class="event_name">Dramatic Performance</p>
        <p class="signature_block">
            <span class="signature">Thomas Beck</span>
            <span class="position">NYCFL President </span>
        </p>
        <p class="date_block">
            <span class="signature-date">09/26/2020</span>
            <span class="date-label">Date</span>
        </p>
    </div>
</div>

I found a royalty-free guilloché border vector image and found a few suitable web fonts with the right look. My reference certificate was a Word Document based on a print template from an office supply store. When translating a design into HTML/CSS, we usually use units like pixels or REMs, but in this case, it was easier to use inches, a less commonly used unit in web design. That allowed me to make the full size of a certificate to be based on US Letter paper size (8.5 x 11 inches).

div {
    overflow: hidden; 
    height: 8.5in; 
    width: 11in; 
    padding: 0.5in;
}

Because certificates are fixed-size documents, HTML print styles made it easy to produce consistent, printable layouts.

Templates

The core idea was to extract data from Tabroom, the software we used to run tournaments and use it to generate the certificates. Tabroom was built with a programmer’s mindset and makes much of its data available as comma-separated-value (CSV) exports. There were several types of reports we wanted to generate from this data so I decided the best starting point was to parse the files once and import the data into a database.

The basic workflow would be:

Import CSV results
Store in database for reuse
Render certificates using a template
Export as printable HTML/PDF

I decided to use Quarkus to scaffold the application along with its Qute templating language. Its quick startup time, developer tooling, and simple Jakarta EE API implementations made it a great choice for building a prototype that could evolve into the final product.

Students compete in one of several categories. For each category, I would get a final results CSV file that looked something like this. I used the Apache Commons CSV library to parse the files.

Ranking	Code	Name 1	School
1	508	Jane Doe	Some Academy
2	512	John Smith	P.S. 1337

Since I would be the one generating the certificates, I used an H2 file-based database. We were all working remotely so both the application and the database file lived on my desktop. When I needed to generate something, I could start up the application using Quarkus development mode.

To interact with the application, I created a REST API that could power a small React front end. Below is a simplified version of the JAX-RS resource. Most of the endpoints are general CRUD operations. These endpoints provided for the following workflow:

create a tournament with basic information like the name, date, and virtual host school
create a list of events in the tournament
upload the CSV results for each event
render the certificates into the template

@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class CertificatesResource {
    @Inject
    Template certificate;

    @POST
    @Path("/tournaments")
    public Tournament createTournament(Tournament tournament);

    @POST
    @Path("/events")
    public Tournament createEvents(EventList eventList);

    @POST
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Path("/tournaments/{tournamentId}/events/{eventId}/results")
    public Tournament addResults(
        @MultipartForm MultipartBody body,
        @PathParam("eventId") int eventId,
        @PathParam("tournamentId") long tournamentId
    );

    @GET
    @Produces(MediaType.TEXT_HTML)
    @Path("/tournaments/{id}/certificates")
    public String generateCertificates(@PathParam("id") long tournamentId);
}

The generateCertificates endpoint would render the Qute template.

<link rel='stylesheet' href='/certs.css' />
{#for event in tournament.events}
{#for result in event.results}
<div style="overflow: hidden; height: 8.5in; width: 11in; padding: 0.5in">
    <div class="certificate_border {result.certColor}">
        <div class="certificate_body">
            <img src="/nycfl-logo.svg" height="100px"/>
            <p class="nycfl">New York Catholic Forensic League</p>
            <p class="award_certificate">Award Certificate</p>
            <div class="tournament_details">
                <p class="host">{tournament.host}</p>
                <p class="tournament_name">{tournament.name}</p>
                <p class="tournament_date">{tournament.longDate}</p>
            </div>
            <p class="place">{result.placeString}</p>
            <p class="before_text">This certificate is given to</p>
            <p class="name">{result.name}</p>
            <p class="before_text">to recognize outstanding performance in the category of</p>
            <p class="event_name">{event.name}</p>
            <p class="signature_block">
                <span class="signature">Thomas Beck</span>
                <span class="position">NYCFL President</span>
            </p>
            <p class="date_block">
                <span class="signature-date">{tournament.shortDate}</span>
                <span class="date-label">Date</span>
            </p>
        </div>
    </div>
</div>
<div style="page-break-after: always; visibility: hidden"></div>
{/for}
{/for}

In the first version of this, I had several border images to produce different placements. Gold for first place, silver for second, bronze for third, red for fourth through sixth place, and light blue for any other finalists. I quickly realized that it would be beneficial to have more flexibility to support more placements and custom designs without maintaining multiple static images. Thankfully, since the border was an SVG file, I could also turn it into a Qute template as well and add one more endpoint that would adjust colors in the SVG.

@GET  
@Path("/background.svg")  
@Produces("image/svg+xml")  
@PermitAll  
public String getBackgroundImage(  
    @QueryParam("color") @DefaultValue("ffffff") String color,  
    @QueryParam("color2") @DefaultValue("323131") String color2,  
    @QueryParam("color3") @DefaultValue("323131") String color3  
)

And we could reference this endpoint in CSS like this:

.certificate_border.gold {
    background-image: url('/certs/background.svg?color=D4AF37');
}
.certificate_border.black {
    background-image: url('/certs/background.svg?color=D8D8FF');
}
.certificate_border.silver {
    background-image: url('/certs/background.svg?color=C0C0C0');
}
.certificate_border.bronze {
    background-image: url('/certs/background.svg?color=CD7F32');
}
.certificate_border.red {
    background-image: url('/certs/background.svg?color=C76C67');
}

Finally, since the certificates were rendered as HTML, generating PDFs was straightforward. I used Chrome’s built-in “Print to PDF” feature, which handled layout and pagination reliably without needing additional libraries or tooling. While this wasn’t fully automated, it was simple and dependable—and more than sufficient for our needs. For ease of downloading, I uploaded the resulting PDF to an Amazon S3 bucket because the file was too large to email.

On September 30th, I sent out the first set of certificates for our first online speech tournament, 45 pages altogether, and it was just the beginning. Soon, I needed to accommodate events with other formats, larger tournaments with quarterfinals and semifinals, tournaments for other leagues, and customization for other purposes. The strength of the original implementation was how easy it was to evolve. I’ve since generated certificates and slides (more on that later) for over 150 tournaments, and the software has continued to evolve.

Lessons Learned

HTML and CSS work well for print layouts. Browsers provided a reliable and flexible way to generate certificates without specialized tooling.
Templates make scaling easy. Once the certificate layout was templated, generating hundreds of certificates became trivial.
SVGs can be treated as templates too. Converting the border into a template made it easy to customize designs without maintaining multiple assets.
Manual steps can be the right starting point. Using Chrome’s Print to PDF feature was simple, dependable, and fast to implement.
Simple systems can go a long way. A lightweight architecture was enough to support over 150 tournaments and six years of iterative feature development.

A Programmer's Journey

Frank Riccobono — Sat, 20 Jul 2019 00:00:00 +0000

I was fortunate to be introduced to computers at an early age. According to an old school report I found in my hoard, we got our first family computer when I was four. You probably wouldn't take my dad for your typical computer geek, but he latched onto the technology when it started transforming the workplace. He, in turn, taught me the basics. By the time I was five years old, I already knew a handful of basic DOS commands. (At that point it was limited to switching directories and launching games – Reader Rabbit was an early favorite). By eight, I was using Microsoft Office to write silly short stories and PowerPoint to make “art."

I started programming almost by accident. Although I liked school and my teachers, I wasn't quite a star student in my earliest primary education. I hated coloring inside the lines, my penmanship was atrocious, and I've always tended towards absent-mindedness. I would forget to do homework or frequently leave books at home. That changed once I got to third grade and even more so by fourth and fifth. That's the point where school became less about learning behaviors and more about acquiring knowledge. I was (and still am) insatiably curious, and this new chapter of education was what I had been waiting for. I was also very impatient. I would look ahead in my textbooks, anxious for the next lesson even before the current one had fully sunken in. What was worse was that many of our books were longer than we'd be able to cover in a school year. I found myself particularly drawn to the final chapters that we would otherwise never see.

One day in fifth grade, something in the appendix of my math textbook caught my eye. It was an extra credit assignment of sorts written in a mono-spaced font. The instructions said to type the instructions into a program called QBasic, which at that time was still bundled with Windows. I don't quite remember what the program was, but it was something simple like a coin flip simulator. Whatever it was, when I entered the instructions, it worked! I was experiencing some new kind of magic that I didn't fully appreciate at the time. I flipped through the book and found a few more extended code listings and tried them out. I was exclusively following the textbook instructions, though. I had no idea what any of the keywords meant, and it never occurred to me to change anything or to try to write my own program.

BASIC...the entrypoint for many a programmer

Another joy at that time was the annual Scholastic Book Fair (I’m a nerd if you haven’t figured that out by now). A year or so after my first foray into QBasic, I found a book and accompanying CD at the book fair called“Learn to Program BASIC” by Interplay. In it, a bizarre-looking cartoon character named Media Man( reminiscent of Clippy) taught you through wacky video clips how to write a dialect of BASIC developed by the game company. I learned about strings, subroutines, sprites, arrays, and much more. I still didn't stray far from the tutorials, but I was able to internalize much of the material. In particular, programming in an XY-coordinate system gave me a leg up in math class when we started learning how to plot various graphs. It also helped in Computers Class where Sr. Blanche was introducing us to Logo.

LTPB felt more like a video game than a useful tool, though, and I lost interest when I’d finished all the lessons. I still never thought to try creating something original, and I did not do much more than that until another coincidence occurred in high school. I was chatting with a friend at the end of freshman year, and we somehow got into the topic of programming. His father was a programmer, and he was learning Visual Basic 6. I'd never heard of it, but it had Basic in the name, so I assumed it was similar to what I'd seen before. He agreed to teach two other friends and me. The four of us had bold plans to create a video game company that summer, powered by VB6. Those plans never materialized, but I did learn the language and my friend, the ringleader, did write an Apple Catcher game that "went viral" in the sophomore class (before "going viral" was a thing).

Part of the problem with our ill-fated video game company endeavor was that we couldn’t agree on what type of game to make. I had suggested an RPG, not imagining at the time, how much work was involved. I spent the summer learning a bunch of things including how to do Bit Block Transfers (BitBlt) to remove the backgrounds from sprites (something I missed about LTPB), how to generate tile-based maps, and, most-ambitiously, how to implement the A* path-finding algorithm. When that last one (mostly) worked, I was ecstatic. Mind you, at that time, I still had no sort of formal training.

Throughout the rest of high school, I dabbled in various other technical things. I learned HTML/CSS in the age of CssZenGarden. I set up a personal website on Tripod and even wrote a few Perl-CGI scripts to automate some of the maintenance of it. My dad found this browser-based 3D game engine from Wild Tangent that allowed you to write in Javascript. I built a few simple websites for a theater company I was working with at the time. One of my favorite TV shows at the time, The Screensavers, introduced me to Linux and I started playing around with that in my spare time. It was all a hobby for me. I had no idea that I could make a career out of it.

My first website...what was I thinking?

When the college admissions process started in my junior year, I received an advertisement for a summer program at one of the schools I was considering (Stevens Institute of Technology). The program allowed high school students to take an online college-level class over the summer. I signed up for CS115, Introduction to Computer Science. I didn't know what "computer science" was at the time, but the syllabus mentioned programming, and that was enough for me. The class involved learning Java, which had enough in common with VB6 that I was able to pick it up pretty quickly. That class convinced me to choose the heretofore unknown Computer Science as my major when the time came.

I ended up attending Stevens for college. It was a blur of languages including C, PHP, Assembly, Scheme, Matlab, MySQL, and even a smidge of COBOL. Like most graduates, I thought all that was everything I needed to know about programming. One concept I later learned was conspicuously missing from the CS course load was the idea of "Legacy Code" and how to work with it.

My first job out of college had me working with a several-years-old Java project that had been cobbled together by outsourced contractors. I can't say too much about the experience due to confidentiality agreements. It suffices to say that academic knowledge of Java did not prepare me for J2EE, or for making sense of tens of thousands of lines of code and a bunch of terrible variable names. I was not given a lot of guidance since our lead developer worked remotely and only at night. And my conservative inclination left me afraid to change much. I did eventually get to the point where I could contribute to the project. I was writing software for a business, but I had no real sense of what business software engineering entailed.

Programming in the "Real World"

The next milestone didn’t come until three years later. There were two sources. First, I was taking some graduate-level classes in Natural Language Processing, a topic that had long interested me. As bad as corporate code can get, academic code is generally worse. PhDs and grad students typically write software for an upcoming paper and, unless their discipline is software engineering, they usually don't write with maintenance in mind. "Battle-scarred" as I was by the corporate world, I rejected this writing style and strove to try to make any code I wrote for those courses as clean as possible. This goal required reading lots of tutorials outside of class, but I think it paid off. Most of those courses required us to code in Python, and I made an effort to learn the Pythonic way. For the first time, I wasn’t just thinking about whether or not my code worked but also how it was structured.

The other influence was a part-time gig I took on in between grad school semesters. One of my college professors contacted me regarding an opportunity with a startup looking for an intern. They were developing a Ruby on Rails e-commerce site. Ruby and Python had enough similarities that I was able to pick up the former pretty quickly, but Rails was eye-opening. I had never used a framework. I was fascinated by tools that not only reduced boilerplate code, but that also imposed structure on the application.

On top of that, the team was also using Capistrano to automate building and deploying the app, and they had AUTOMATED UNIT TESTS through rake! I had used simple makefiles in my college C-programming days, but, for a technology aimed at creating efficiencies, programming and testing of programs always seemed very manual to me. My college professors had even convinced us not to use IDEs when learning because they introduced too much magic. The idea that you could introduce automation and tooling seemed revolutionary.

In the end, the startup didn't work out (long story for another time, but no hard feelings toward anyone involved). In the meantime, I found myself in the lead developer role for that software product I had started working on after college. The time had come to put some of what I'd recently learned to use. Over the next few years, a junior developer and I worked to wrangle the legacy code. We imposed structure where there was disorder and wrote automated tests where there had been none. It was exciting.

All Hail Test-Driven Development!

Today we’re working on a new system. We’re using technologies like Hibernate in the back-end and React in the front-end. It's been a bit of a paradigm shift from never using any frameworks. There are various challenges and successes every day, but the best part is there is always plenty to learn. I can still be that curious kid, stealing furtive glances at advanced topics, that I was when I started.