Documentation for any code is key. Most people will want to read your code to understand your methodologies and the operations you used to come to a solution. I definitely have come across spaghetti code (A bunch of functions with really no comments and just loosely thrown into a notebook) many times when reading other people’s codes, but I would be lying if I said I don’t make the same mistake myself. Reading this code can be a hassle and become an arduous process with little understanding gained once completed. Fixing your spaghetti code and cleaning it for other users is important for getting your ideas across to other people, but also for allowing them to understand and utilize the code you created!
Ways to clean up your code
There are many ways one can clean up their code. Today we will walk through the progression of going from spaghetti code to beautifully written code with gorgeous outputs that outline your math equations.
Clean up 1 → Add documentation
To begin, let’s say you’re creating a Pythagorean Theorem function. First, you create two functions to define the sides (obviously you could just set a and b to integer values).
def side_1(a):
side1 = a
return side1
def side_2(b):
side2 = b
return side2
Now, let’s create a function for the Pythagorean theorem.
def pythagoreanTheorem(a,b):
c = math.sqrt(a**2 + b**2)
return c
Putting this all together, but now with comments will really clean up the code and make it more understandable to a user. T he code originally allowed for sides a and b to be negative, therefore, exception handling raises an error if negative values are given. Additionally, we’ll get rid of those useless functions we began with for gathering the sides and just have the user input two sides to reduce the code (ie. lean code). Finally, we can rename the function to more explicitly explain what it does and add documentation to explain the assumptions of the function.
import math
def hypotenuse_frm_pythagThrm(side1: float ,side2: float) -> float:
"""Assuming a the triangle has a 90 degree angle.
Arugments
---------
side1 (float) : A float value for the first side of a triangle
side2 (float) : A float value for the second side of a triangle
Returns
--------
side3(float): The calculated hypotenuse
"""
if side1 =<0:
raise ValueError('A triangle can not have a negative length!')
if side2 =<0:
raise ValueError('A triangle can not have a negative length!')
side3 = math.sqrt(side1**2 + side2**2)
return side3
Now, look at that! Even though we are working with simple functions, just adding some documentation, exception handling, and removing useless functions has made our code more physically pleasing to the eye. The additional step of including exception handling ensures people will understand why they are breaking your code. What can make this code look even better? Transforming the output of our code with latex font.
Clean up 2 → Latexify
As I stated, we can clean python math functions using latex format. The latex format is highly regarded by various STEM disciplines and is used when publishing research and writing about mathematical/engineering processes. Originally, we outlined the Pythagorean Theorem as
def pythagoreanTheorem(a,b):
c = math.sqrt(a**2 + b**2)
return c
Now, what happens if we use latexify on this function? (Note: Latexify did not work with my document functions but will work if you simply the function to a return statement. It could still be helpful to do this in your code and hide the input, only showing the output function).
@latexify.with_latex
def pythagoreanTheorom(a,b):
return math.sqrt(a**2 + b**2)
pythagoreanTheorom
After running this cell, we get the following output (WITHIN the Jupyter Notebook):
And just like that, we have made our code BEAUTIFUL! Using this format to express your functions in your code will be super helpful for anyone reading or using your code. Not only does it help overcome the difficulties of reading math equations written in computer language, but also it can clearly outline how an equation operates which is super helpful to those struggling with understanding the operations of an equation.
Conclusion
Not only is Writing fundamentally correct code important but documenting and making it legible to the viewer is key so others can understand your work and how you came to various conclusions. Latexify is an API that can help outline mathematical equations to readers which would otherwise be difficult to read and follow in a programming language format. Try this out before publishing your next piece of work, I promise people will be super appreciative of you taking the extra step!
If you enjoy today’s reading, PLEASE give me a follow and let me know if there is another topic you would like me to explore! If you do not have a Medium account, sign up through my link here! Additionally, add me on LinkedIn, or feel free to reach out! Thanks for reading!