Clean Code: 5 Tips for Best Practices

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!

 

Recent Engagements

I am so, so pleased to tell you, readers, that this past Saturday, I was on a panel of women answering attendee questions about their careers during Hyland’s first Women in Tech conference! Here’s the official press release blurb:

“Hyland will host the Women in Tech Conference on Saturday, October 8 at its headquarters in Westlake, Ohio. Working with close partners the Ohio Collaboration of Women in Computing (OCWiC) and We Can Code It, the half-day conference aims to inform women about the career opportunities within computer science and information technology (IT) professions.

Attendees will hear from female software developers, quality assurance (QA) specialists and senior IT managers who will provide insight into their technology backgrounds, what interested them about their chosen fields and the roles and responsibilities for their positions.”

Source: http://www.prweb.com/releases/2016/10/prweb13733094.htm

Feedback for the event has been overwhelmingly positive. It was a great day at Hyland for those of us who were speaking, and I’m really glad to hear that it was a great day for our attendees, too! There was a lot of good energy in the room that came from over fifty women in one place with one goal: to represent and increase the presence and visibility of women in technology. The conference opened with a talk by Brenda Kirk, Hyland’s Senior Vice President of Product & Strategry (and my big boss!), followed by a presentation by two of our developers, the Q&A panel where attendees asked us about our career paths and opportunities at Hyland, a talk by my frentor (that’s friend + mentor, for those unaware) Mel McGee of We Can Code IT, and a presentation by volunteers and attendees of the Ohio Celebration of Women in Computing (OCWiC).

For more information on Hyland, We Can Code IT and OCWiC, check out:

I was also asked to speak at a recent We Can Code IT commencement, but that’s its own blog post, and it hasn’t been written yet! I’ve been keeping busy lately and am looking forward to finally being able to give updates on all the projects I have going on, including a new website (here’s a hint: I now own http://www.mylittlecoding.com) and a new meetup group. Stay tuned. 🙂