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. 

Version Control

Version Control: the Missing Link

Version Control is an integral part of software development. Allowing developers to track changes to software, version control systems give programmers the power to collaborate, discover erroneous changes, and compare versions of software. When rightly used, version control (also called source control) empowers developers to make and share complex changes without fear of losing previous implementations. Developers who use revision control can always look back on and—if necessary—revert to previous versions of the software. Unfortunately, I received two-and-a-half years of Computer Science education without hearing about version control once.

Encapsulating Functionality

Computer science authors and professors often discuss the concepts of encapsulation, abstraction, and information hiding. These concepts are fundamental to programming, and they are required in order to manage complex systems. By encapsulating information into separate components, programmers can reason about those subsystems alone. Instead of understanding and mentally grasping the whole system at once, coders can partition systems into coherent sections. Unfortunately, encapsulation, abstraction, and information hiding are usually discussed with respect to objects and object-oriented programming (as you can see in the links above). But encapsulation is equally important in the lower-level tools of functions and methods.

Step Through Your Code

Take a look at this code:

public interface ResourceHandler {
    public Resource createResource(String resourceName,
        String resourceLibraryName);
}

/* ... */

String resourceId = "resourceLibrary:resourceName";

/* ... */

String[] resourceInfo = resourceId.split(":");

/* ... */

resourceName = resourceInfo[0];
resourceLibrary = resourceInfo[1];

/* ... */

resource = resourceHandler.createResource(resourceLibrary, resourceName);

Although the code runs correctly, it would be problematic for future maintenance because there are two subtle errors in it. So, what is wrong with this code?