Last week, another developer from Hyland and I had the opportunity to go out and give a talk to computer science students at Bowling Green State University, courtesy of the university’s Women in Computing club. They were kind enough to let us choose our own topic, and after tossing out our first 50 ideas, we decided to talk about how to write clean code.
Both Rebecca and I are second-career developers, and the two of us are called on to give the “second-career-woman-in-tech” talk fairly often, so we wanted to talk about something technical! Besides which, university comp sci majors are probably not a group that needs a “second career” talk. We headed out to Bowling Green after work on aWednesday, had a lovely drive out, and spent a few hours giving the presentation and chatting with the students.
I don’t want to dump the entire presentation here, but I did want share some of our key points. Also, if you have an organization that’d be interested in hearing the talk, drop me a line and one/both of us can make arrangements to come give it!
Point #1: Coding is a social activity. Programmers spend more time reading code than we do writing it! The ratio on reading to writing code when it comes to development is something like 60:40. This is because programming languages don’t exist for computers. Think about it! All the computer cares about are ones and zeros; the switch is either on or off. We have high-level programming languages because programmers have made them for other programmers. Languages are a tool that lets us share ideas with each other and communicate what we’re trying to achieve with our code–which is why you should always write clean code. Pretend that the next developer to touch your code is a psychotic serial killer who knows where you live; you don’t want to make them angry.
Point #2: The two hardest things in computer programming are cache invalidation and naming things. (Admission: I stole this saying from my dude Dave Goerlich). You want to make sure that your names for things convey your intent! Follow common conventions for whatever language you’re using, use one word per concept (i.e. don’t use “get”, “fetch”, and “retrieve” if they all mean the same thing), and avoid one-letter variable names (unless it’s a short scope or you’re naming an iterator variable). Variables (customerAccountNumber) and classes (customerAccount) are nouns, booleans are yes/no answers (isValidAccount, isNotFlagged), functions are verbs (getCustomerAccountNumbers). You also don’t want to mislead your reader–so don’t name an array of Customer objects a “customerList”. Names should also be pronounceable and understandable–don’t make weird acronyms, or use nonsense words that have no meaning outside of very specific knowledge set.
Point #3: Classes and functions/methods should be small! Very small! Very, very small! They should also obey the SRP (Single Responsibility Principle). Functions should do one thing and do it well; classes should only have one reason to change. For functions, the ideal number of arguments is nil–then one, then two, perhaps, three, but after that, many input arguments are a bad smell and indicate that the function is probably not adhering to the SRP. Stay away from output arguments if at all possible–we’re far more used to seeing input arguments, and output args can lead to confusion.
Point #4: Keep it DRY. Don’t Repeat Yourself! This argument may have been done to death a thousand times before, but it’s worth repeating in every talk about clean coding practices. We can also talk about organization here: try listing your functions ordered by level of abstraction. One function should call those functions directly beneath it, although there are (of course) exceptions to this rule (I had one in my example code!). Try making your code as easy to read as possible so that they next developer doesn’t have to keep scrolling up and down lines, looking for the next function call.
Point #5: Comments can be evil. It’s very, very tempting to comment away badly-written code, but that’s a cardinal sin of clean coding. Comments are not an excuse for skipping refactoring–if you think developers are bad at maintaining clean code, imagine how bad we can be about keeping comments up-to-date! Comments that are redundant, misleading, or arbitrarily-required need to go, as do large block of commented-out code. End-of-block comments are a smell that your code block is too long and refactoring is needed, and log comments on every file aren’t needed with any good modern version-control system. Documentation comments, TODO comments, legal disclaimers, and short informative or clarifying comments can be good, but these all still run the risk of becoming outdated, and care should be taken to update them along with the surrounding code.
That’s not the entirely of the presentation, but those five tips are our key points for code cleanliness. Also, if you’d like to see our slide deck, you can see it here!