Coding best practices for Academia: Bridging the Gap between Research and Industry

Post by: Beverly Setzer

Edited by: Caroline Ahn, Joseph Chen, and Brendan Williams

As academic researchers, we usually write scripts independently and without much guidance since we often work on projects alone. Thus, we focus on getting code to work rather than its readability or efficiency, but this can result in clunky code that is hard to validate. In contrast, software engineers receive formal training on writing clear and efficient code and work in teams, where code review and collaboration are essential. Despite our lack of training, it is extremely important that our work is reproducible and that our code is well tested and easy to read. Lack of proper coding etiquette and review can lead to mistakes, causing heart-pounding moments as we frantically double-check results. To avoid some of these nail-biting moments and ensure our code is efficient, reproducible, and clean, we have compiled a list of suggestions, beginning with general coding practices and ending with more specific tips from such software engineers who write code professionally.

General coding practices to write clean, readable code.

·  Adhere to a coding style guide, like this one, which outlines the style and best practices for your code. Strive for clarity, simplicity, and maintainability.

·  Give your variables clear and descriptive names. It may take a bit longer, but it will be worth it for yourself and others when revisiting the code.

·  Make chunks of code into reusable functions. If you find yourself copying and pasting code, make it a function. Also, if the analysis can stand on its own and may be useful in different contexts, make it a function. This reduces mistakes and makes the code easier to read.

·  Document your code. Write comments as if others will read through your code. Explain each variable and step, as you may not remember the context after a year. Comments save time in the future.

·  Read other people’s code. Study the code of experienced coders in your lab and take note of what practices they follow.

Tips from senior graduate students.

·  Visualize everything. Plot each piece of data and transformation to quickly spot any errors.

·  Test functions using simulated data. Define the expected output and verify that the script works with simple examples.

·  Use version control even if you are not collaborating. Familiarize yourself with Git or similar tools to track changes and compare versions of your code for debugging.

·  Ask for feedback. Before submitting an abstract or manuscript, have someone in your lab review the code line by line for accuracy.

·  Choose your programming language based on what will be most efficient for each script. Each of the three popular coding languages have their own strengths and weaknesses. You don’t have to commit to one language for your whole project. For example, you could do your data preprocessing in Python and analysis in MATLAB.

·  Use your resources! Ask the people around you for help or use the internet to find solutions. Online, you can use Stack Overflow, which has peer reviewed solutions to coding problems, or ChatGPT which can generate specific solutions to your problem. You can even use ChatGPT to generate documentation for your code sections! Either way, make sure you double check for accuracy before integrating the suggested solutions.

·  Get a Coding Duck to explain your code to! These can be helpful for clarifying what each line or block of your code should be doing, writing documentation, and identifying errors in your code by articulating them in natural language. 

Finally, here are tips from two professional Software Engineers, Manan Monga and Shubham Arora. 

·  Make incremental changes and test as you go. Instead of writing your entire code at once, make small changes and test each step as you go. This approach will make debugging much easier. This is especially important if you are using version control software, such as Git, where each incremental change should be its own commit.

·  Simplify your code. Once your code is working, simplify it by removing any unnecessary elements. Focus on writing clean and efficient code.

·  Stay up-to-date. Regularly look up information on Stack Overflow to stay updated on new functions and packages.

·  Be creative. Feel free to be creative and experiment with different ways to write code. This can make your code more expressive and there is not one correct way to make something work.

·  Reframe the problem when you’re stuck. Explain it to someone or write a paragraph about it to work through the logic before writing it in code.

Hopefully implementing some of these practices will help you avoid mistakes and stress. Thank you for reading and happy coding!