Seven Essential Programming Conventions and Best Practices
What is convention when it comes to coding? Why does styling matter if my output is correct?
Many have trouble navigating this topic while entering the field of software engineering. As a student, they are typically working independently or in small groups to pass a series of tests or piece together a project. But upon joining the workforce, they realize much of their time is spent looking over source code from previous developers.
Coding conventions are a set of guidelines for a specific coding language that recommend programming style, practices, and methods for each aspect of a program written in that language. This improves readability of that code and more easily allows for software maintenance.
There are professional standards that are adhered to for every industry. You wouldn’t tell an accountant to skip the double entry bookkeeping when in a rush to meet a deadline. You wouldn’t tell a doctor to skip washing their hands if you are in a hurry. We have respect for people in these professions and how they work. As programmers we must advocate for the quality of code we write and insist on doing it the right way.
Each company will have their own guidelines that you should spend time practicing. But here are seven general ways to ensure your code is alway easy to navigate:
1. Keep Your Code DRY
DRY stands for “Don’t Repeat Yourself”. Object-oriented principles are built to help you avoid duplicating code throughout your application. Instead of repeating similar code in many places, it is best practice to re-use code at all times possible. And when you inevitably go back to change a variable or method, the adjustment can be done in just one place.
2. Give Variables and Methods Useful Names
Nothing is more frustrating than a developer joining a project only to come across variables with undescriptive names like ‘PL4’ or ‘Z8’ or long too-descriptive names like ‘assign_to_most_recent_user_if_nil’. Variable and function names should quickly tell you what it is and what’s going on.
3. Follow Styling Principles of your Coding Language
Each framework has certain practices that are specific to that language. For example, in Ruby we use CamelCase for classes and modules definition. We use snake_case for files, variables and methods. One of the best Ruby tips to keep your code readable is to use a ‘?’ to define predicate methods. Predicate methods always return either true or false. Ruby has a naming convention where predicate methods end with a question mark. A prefix like is, are, or has helps the developer to distinguish a boolean from another variable by just looking at it.
4. Maintain a Clean File and Folder Structure
You should avoid writing all of your code in one or two files. That won’t break your app but it would be a nightmare to read, debug and maintain your application later. Keeping a clean folder structure will make the code a lot more readable and maintainable.
5. Keep the Code Concise
The code should always be simple. Complicated logic for achieving simple tasks is something you want to avoid. The logic one programmer implemented may not make perfect sense to another. So, always keep the code as simple as possible.
6. Avoid Using Too Many Comments
The code should speak for itself. Comments are often used in cases where the code is not clear enough on its own. But when code needs to be changed, often the corresponding comments are forgotten. This can lead a future developer down the wrong path. Of course there are good cases when a comment can be useful, like when you are explaining behavior. It is best practice to ask yourself, “Is this code expressive enough by itself?” before adding comments.
7. Methods Should Have a Single Responsibility
A method should do one thing well. It is better to create multiple methods if you anticipate seven different outcomes for a method. The same goes for classes.
There are good practices that could be applied across all frameworks and languages. Everyone who follows a code convention is on the same page. These practices have been established years ago and have withstood the test of time. Many developers have contributed and agreed upon them.
Conventions and best practices are sometimes provided by a formal document depending on the size of the company you are starting at. Often they are listed in a simple text file somewhere in the code base. Or sometimes you will just have to get yourself familiar with the source code. It is important that your code is written in a similar way. You never want to change existing code based on your personal convention habits which can be very subjective.
Be sure you take some time to learn code conventions as it could greatly benefit your career.