The Subtle Art of Sumptuous Code
To be able to code is a skill, which needs good knowledge to be appreciated. And I can say that many developers aren’t able to perceive the art behind a piece of code when they see it.
Being a good programmer isn’t just about writing a few lines of code but is also about writing readable and productive programs that are easy to manage and upgrade if needed in the future. Coding has become one of the most common activities people do. However, their coding practices are often unpolished.
Each one of us has our own way of writing those magical lines. Some use white-spaces while some press a tab; some use comments while others find them useless. As time passes, it’s not just the quality of code that gets upgraded, but the practices followed as well. Here, I have tried to sum up the best coding practices, which may seem trivial to a few readers, but are certainly not something to be overlooked. For new programmers, these can be the mantras that will stick with them till the end. So why not dive right into it!
Writing readable code
On the surface, readability may seem subjective, something which may vary with languages, codebases, and teams. But when you look underneath, there are core elements within all pieces of code that make them readable. Here are a few of the good practices that I’ve learned throughout my experience with coding:
- Getting rid of dead code: While writing programs, we often add irrelevant pieces of code. They create nothing more than confusion for the programmer when they go through them at some point in the future. Try to get rid of such pieces of dead and useless code.
- Proper Formatting: Code formatting is one of those things that you notice only when it is absent. Usage of proper indentation, capitalization and naming conventions, etc., may seem obsolete, but it is actually one of the most important qualities a good programmer possesses.
- Objects over procedure: Using objects while writing code is advantageous over procedural methods. It helps the coder in terms of code reusability, data redundancy, security, code maintenance, and better productivity.
- Understandable Naming conventions: Using proper and understandable naming conventions to name functions and variables is a practice followed by good programmers.
- Commenting: Providing brief and descriptive comments in front of every important portion of the code can help others understand what that piece of code actually does in the main program.
- Following Symmetry: Last but not least, following symmetry, while writing code is highly appreciated and is one sign of being a good programmer. Equal indentations and white-spaces used throughout the code makes it look clean and easy to read, and even easier to debug.
Understanding Version Control
Whether it is for personal projects or organization-level projects, version control is one of the most important skills for a developer. It is a tool that helps developers/programmers to tackle some everyday problems, such as tracking changes in the code, maintaining code, and allowing them to work on the same source code files without affecting each other’s workflow.
The concept of version control is often facilitated through special kinds of systems called Version Control Systems (VCS). These systems have gone through many developments over recent years.
Version control systems are special types of software development tools designed to help software developers track any changes made on a specific application's source code. The most popular VCS nowadays used by millions of developers and programmers around the world is Git. However, there are also other VCS like PerForce, Beanstalk, etc., that are quite common.
Version control in itself has become one of the essential parts of a programmer’s life. Using a VCS has various benefits like:
- Collaborative contribution: The main benefit of VCS is that it allows us to contribute to projects we like despite being at different places without disturbing the actual program.
- Testing purposes: Having different clones of the same software project can help people test new features if any, and make sure they function properly.
- Keep history: These systems help us keep a backup and a record of the changes made in a specific code file that could help others understand how a specific piece of that code came to be.
- Backups: One of the most vital benefits of using a version control system is that every time a contributor clones a repository, they are, in a sense creating an additional backup of the current version of that repository.
VCS may sound very sketchy to a few, but honestly, it is not. It is just one of the toolkits designed to make a developer’s life easy-peasy, although…
The art of googling bugs — Debugging
Coders spend long hours debugging, staring at the codebase, and figuring out what exactly went wrong. That’s something ubiquitous among developers who don’t know the correct techniques to find the bugs and fix them. It becomes easy to learn the correct approach to follow to kill that bug hidden inside your code like those cockroaches in your kitchen.
- Googling: I’m not going to sort those tips by usefulness, but googling error messages is first for a reason. If you can’t understand an error message at first encounter, the easiest way to solve the problem is to google the error message.
- Log(everything): Logging is one of the most popular ways of debugging code. Using statements like console.log() or print() at correct positions may help you understand what’s wrong with your code.
- Program localization: The problem localization method's key idea is to comment/remove a code step by step until you figure out what went wrong. It is beneficial when you are writing an algorithm for a pretty long time without compiling and executing the application.
- Analyze logs: Yes, I can understand. Going through those boring and lengthy logs can be hectic most of the time, but it may help you understand the issues with your code.
- Ask a friend: One of the best but underrated methods of debugging is simply asking a friend. Good developers are always ready to help.
- Rubber duck debugging: This is so far the best thing I have learned in my entire coding experience. The method suggests starting to explain your code to a rubber duck line by line, and you will end up noticing the tiny details about your code, which might create the actual issues. You can read more about it at rubber duck debugging.
It’s funny how a small rubber duck can help you fix a large chunk of bugs in your code.
- Debugger at the rescue: I presume most developers are already familiar with how debuggers work and why to use them. But as a personal opinion, using debuggers kills your analytical and thinking skills, which is why I am keeping this point as the last option for you to consider.
Good documentation
Being able to write good code is good, but being able to write good docs, well… that’s a talent. But why write those lengthy docs after hours of code writing? The answer to this question is simple: to tell other people about your code's key features.
Documenting your programs is considered one of the best practices in a coding culture. It helps not only others but also ourselves. A good way to start would be simply updating README.md for your projects. Remembering large chunks of codes can be hard sometimes (actually most of the time), but going through well-framed docs can help you to understand the code later at some point of time while you might be scratching your head trying to understand why you wrote that particular part of the code.
Now here comes a question, What makes good documentation?
People often think that the value of docs is subjective or unquantifiable. This is rarely the case.
The value of writing is that it can be written once and shared many times, whereas in-person or real-time communication forms need to be repeated each time a new person needs the information.
The question here is not “How” to document but “What” to document?
- Document questions that are clearly or probably going to be asked
- When you get asked a new question, you might as well write it in a generally-applicable way if possible and quickly insert it into the best location in your document structure.
Okay, so what shouldn’t be documented then? Even that has an answer.
- Things nobody cares about
- Things you are proud of, but really only you care about, like how hard you worked — tell your mom or write a blog post.
The trick is to anticipate the probable audiences for a subject matter and what they probably need to know.
So much for the value of a doc.
What about the quality of a doc? Isn’t this subjective?
No. Not at all. Doc has a job to do. It is good inasmuch as it accomplishes that task; that is an absolute and completely objective standard to the quality of technical documentation. Suppose I write a document for experienced Kotlin engineers and, out of 100 engineers, 23 understand it. No matter how smart I think I am, I have failed. That score will save very few people any time.
Good docs follow the 4C principle, which says that your documentation should be:
- Concise: Writing more words than required is certainly not an appreciated practice anywhere. And readers oftentimes are not patient enough to read something that doesn’t add value. So wipe out those extra words from your docs!
- Complete: Try to include everything that somebody is likely to want to know. Please do not include things that will not help other people with their work.
- Correct: Get someone else who understands your content to sanity-check it for correctness. If readers find your document inaccurate, they will wonder why they should read your work anymore. In some situations, erroneous information can cause serious harm.
- Clear: Clarity is the objective. If your intended audience does not understand your docs, your docs are not clear.
Well yeah, that’s all you need to know to become a good programmer. It is not easy, but it is a skill that one can develop by practice.
Computer science is not just for smart ‘nerds’ in hoodies coding in their basements. Coding is extremely creative and is an integral part of almost every industry.
- Reshma Saujani
