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

For VSCode:

https://dev.to/adamlombard/how-to-use-the-black-python-code-formatter-in-vscode-3lo0


Documentation:

https://black.readthedocs.io/en/stable/


3. Intuitive Variable Names and Comments

Variable Names

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.

Comments

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:

  1. https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners

  2. https://www.freecodecamp.org/news/how-to-use-git-efficiently-54320a236369/

  3. https://nvie.com/posts/a-successful-git-branching-model/

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.


Signing off,

Stanley Lo








10 views0 comments

Recent Posts

See All