What a New Coder Needs to Know (Python)

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.


Key Takeaways:

(the section where you've only got time to read on your toilet)

  1. Use a coding template for functions and classes.

  2. Take advantage of a formatter.

  3. Although tedious and inconvenient at the time, make intuitive variable names and detailed comments. It'll pay off in the long run.

  4. Keep a good habit of version control.


1. Coding Template

Advantages:

  • 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 Template:

class XYZ:
    """
    Description: why do we need this class? what kind of functions can we 
    find in this class?
    """
    def __init__(self):

Function Template:

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 Example:

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):
        ...


Function Example:

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