Java Testing Tip #2:

Don’t Clean Up After Tests with RunListener.testRunFinished(), Add a Shutdown Hook Instead

Recently, while I was writing some tests which require a lot of temporary files, I ran into a problem: my tests never cleaned up the temporary files.

Do You Have Teeth?

There is a generation whose teeth are like swords and whose molars are like knives to devour the poor from the earth and the needy from among the human race.

—Proverbs 30:14

This evening, my one-year-old son, Jules, and I took a walk around the neighborhood. While Jules was cruising around picking up sticks, he spotted a woman walking her dog in the distance.

Java Testing Tip #1:

Don’t on Exception, Wrap With AssertionError Instead

Recently while updating and writing tests, I ran into a pattern:

try {
    /* Tested code here... */
catch (Exception e) {"Exception was thrown with message: " + e.getMessage());

Many times when developers are writing tests, they run into a similar situation where throwing an exception should result in a test failure. An uncuaght exception causes a test error, so the exception is caught and is called to fail the test instead. The above code is certainly correct, but it also hides all the information that the original exception contained.

Programming Terms Cheat Sheet

This is a cheat sheet showing various programming terms alongside example code (in Java) of what the terms describe. I created this document to give junior developers and interns a reference for the terms that developers often use to describe different elements of a program. The goal of this document is to allow senior developers to use technical language and be somewhat Socratic during code reviews with new programmers instead of pointing to specific lines and explaining exactly what to do. If a junior developer’s code is being reviewed and he or she is asked, “Why did you pass the obtainClass() method a String variable?”, he or she can quickly search this sheet for the unknown terms and try to answer the question. It will also help new developers to know what parts of the code senior devs are talking about—for example: obtainClass()’s method signature versus an obtainClass() method call. Rather than create an exhaustive reference, I want this cheat sheet to be brief, so I only included the technical words that I use the most during my current code reviews. However, I’m sure this document is not perfect, so if you would like to add or fix something, please write a comment explaining what could be improved and/or make the improvement yourself and send me a pull request.

Technical Writing

Technical Writing: the Missing Link

Programmers are technical writers. Amazing programmers are amazing technical writers. From code to documentation, everything a software engineer does involves technical writing. Developers write code comments, source code, documentation (or wikis), blogs, bug reports, feature requests, questions, answers, forum posts, emails, chat messages, and more. While technical writing is not completely neglected in Computer Science curricula, its importance should be emphasized due to the sheer amount of writing that developers must produce.1 Below I outline some guidelines, principles, and tips which I have found to be helpful for writing different technical documents during my three years as a software engineer.2 The guidelines are by no means exhaustive, and like most rules, they can be broken if there is a good reason to break them. However, I’ve found that these rules help make my documentation clear, concise, and comprehensible.

  1. Due to my strange college career I never took a class focused on technical writing, but that was my own fault since most curricula include it as far as I know. 

  2. In my (nearly) four years at Liferay, I’ve written/edited 9,000+ words of the documentation for the Liferay Faces Project, and I’ve written many code comments, tons of source code, plenty of API documentation (including JavaDoc and VDLDoc), 10 blog posts (6 Liferay blogs and 4 personal technical blogs), 200+ bug reports , 70+ feature requests, 100+ StackOverflow Questions/Answers, 450+ forum posts, and countless emails and chat messages.