I started seriously coding 2 years ago and looking back to how I started reminds me how far I've come. This article is a compilation of all the mistakes I've made and how to be better than I was. WARNING: My coding skills are self-taught so this is just my opinion.
(the section where you've only got time to read on your toilet)
Use a coding template for functions and classes.
Take advantage of a formatter.
Although tedious and inconvenient at the time, make intuitive variable names and detailed comments. It'll pay off in the long run.
Keep a good habit of version control.
1. Coding Template
Consistency for anyone (even your future self) that will make understanding your code very clear
It's easy to implement
Making good documentation for the code will be a breeze
There are no disadvantages to doing this. I'll show you what bad code looks like:
Things to Avoid:
poor naming conventions
lack of comments
lack of class and function descriptions
Why is 73 important? 21? Why are the numbers rounded to 5 decimal places?
Now that I'm reading the code, I barely have any idea of what's going on. Learn from my mistakes and avoid doing what I did. This is code I wrote 1 year ago but we live and we learn.
On a brighter note, here's a beautiful template for you that is designed for object-oriented programming!
class XYZ: """ Description: why do we need this class? what kind of functions can we find in this class? """ def __init__(self):
def xyz(self, variable1: type, variable2: type) -> output: """ Description: function for ... Parameters ----------- variable1: description of what this is, why it's needed variable2: description of what this is, why it's needed Returns -------- output: description of what this is, why it's needed """
class Search: """ Description: Class for all functions needed to search through the graph to produce routescores for a desired product. """ def __init__(self, graph_path, json_file, csv_path, adj_path): ...
def route_search(self, product_smiles: str, final_scale: float) -> csv_file: """ Determines routescore of all routes used to produce product_smiles Parameters ---------- product_smiles: SMILES of desired product Returns ------- results.csv: csv file of the information associated to all routes traversed columns of csv file: - product_name: name of the product of each route - route_name: Index of the route that get to the desired product - route_score: routescore of each route - visited_nodes: list of all nodes that were visited """
2. Black Formatter
Creds to Théophile Gaudin for showing me this.
What It Does
The Black formatter is a neat tool to keep your code looking clean and consistent. This feature can be toggled so that after every time you save your code, the Black formatter does its job. A few things I've taken advantage of are fixing the odd spacings that's important to the indentations, the spacing between functions, and setting the length of each line to <88 chars.
How To Setup
3. Intuitive Variable Names and Comments
As simple and obvious as this sounds, it's not so easy to put into practice. From personal experience, when I begin a project, my mind is fresh and intuitive names will come easily to me. However, as I code and code, I've learnt a lot of the nuances of my code which is good and bad. It's great because I'm fully aware of what my code is capable of, but it sucks when it comes to creating new variable names. The one thing I like to keep in mind:
create variable names that would be self-explanatory outside of the function, class, or even the entire Python file.
EXTRA REMINDER: My coding skills are self-taught so this is just my personal preference.
When it comes to commenting, always provide an explanatory comment whenever you perform something new (usually more than 3 lines of code). Although it is annoying to consistently comment what you're doing which slows you down, people will love you for it (especially self-learners like me). For example,
I try to comment every time there might any confusion at all. We create code for other people to use, and the least we could to do is allow others to read our code. Otherwise, your code will not be used and you do not want that.
4. Version Control - (ex. GitHub, GitLab)
I am nowhere near being an expert on this. However, I understand its value and so should you. Here are a few articles I read that were incredibly helpful:
2. and 3. cred to Martin Seifrid.
Visual Studio Code has a very user-friendly way to connect your GitHub or GitLab directly to its coding environment. In GitLab repos, under the Clone button, there's a button for integrating the repo into VSCode directly. This has proven to be incredibly helpful. Every week or any time there's significant changes, I'll commit my changes and sync it up which directly updates the GitLab repo.
Thanks for reading! I hope my advice as a novice coder might help you as well! I would have definitely loved to hear about this when I first started coding.