3.1 General Programming Tips

Granted: if you are taking this course, then you are a SBS student and not a Computer Science student (so depending on what you choose to do in the future, you may not necessarily need to know programming to that level of detail). However, the following tips (from my own experiences and knowledge) could probably aid you during your programming endeavors:

Be generous with your comments

Programming is rarely a solo effort. Regardless if you’re working on a Bioinformatics project, a web application for a small business, or even something like a hackathon entry, it’s very likely that you will have to work with other developers at one point or another.

For this reason, you should be generous with your comments. You do not want to let other developers guess what a particular block of code does nor do you want to leave any unanswered questions hanging!

Otherwise, if you are just working on a mini side-project, then I would still encourage you to write comments nonetheless. Even if you live and breathe your project’s code, you will forget things from time to time (and this will especially be the case if you don’t code every single day of the week). Hence, if you have written comments, then remembering what a section of code does will be easy!
Ensure that your comments have meaning

Here, I have written a small snippet of Python code; do not worry if you don’t know what the below code snippet does (the focus here isn’t on learning new Python syntax, but best programming practices):
```
# create a variable x
x = [i for i in range(1, 11) if i % 3 == 0]
```
Does the comment above make sense? Yes, but did you gain anything from reading it? No. Even without knowing what [i for i in range(1, 11) if i % 3 == 0] does, chances are that you already knew that I was assigning something to the variable x. The comment is redundant. So, what I could have written is this:
```
# Store the first three factors of 3 in a list called "x"; will be used in <insert purpose here>
x = [i for i in range(1, 11) if i % 3 == 0]
```
How is this comment different from the one before? I stated what x actually is and even stated its purpose in the program. I did not merely state that I was “creating a variable” - rather, what you should aim to do is answer some (i.e., at least one) of the following questions in your comments (note that these questions are not a must - these are more of a guideline):
1. What purpose does the code you are commenting serve?
2. Why did you write the code the way you did (e.g., why a binary search and not a linear search)?
3. What is the code doing?
4. What output (if any) does the code return?
5. Are there any known bugs within the code that you or another developer have yet to fix?
Of course, if you can think of relevant question to consider too, then feel free to answer them in your comments too!
Name your variables something intuitive

Suppose that I have the following code snippet:
```
x = "kevin"
```
Here, you would know that I am creating a variable x with my first name "kevin" as a string. However, x as a variable name is bad: there is no way of knowing what x is without looking at the code!

However, if I did this instead:
```
firstName = "kevin"
```
Things would become a lot clearer, no? The variable name firstName is intuitive enough to the point that you can guess what the variable stores!

Suffice to say that the better your variable names, the easier it is for others and yourself to also work with your code!

Always test your code early on

Testing your code is often one of those things that is included as an afterthought; however, if you have code that depends on other code (e.g., a function that depends on another function), suffice to say that if the function that is being depended on is poorly written, all functions and code that depend on that one function will fail too!

For this reason, I would also encourage to test your code early on. As an example, how about this block of code:

class TreeOrder:
    def read(self):
        self.numNodes = int(input())
        self.keys = [0] * self.numNodes
        self.lefts = [0] * self.numNodes
        self.rights = [0] * self.numNodes

        for i in range(self.numNodes):
            k, l, r = [int(i) for i in input().split("")] # Bad line of code!
            self.keys[i] = k ; self.lefts[i] = l ; self.rights[i] = r

    def inOrderTraversal(self, root = 0):
        if root == -1: return
        self.inOrderTraversal(self.lefts[root])
        print(self.keys[root], end = " ")
        self.inOrderTraversal(self.rights[root])

    def preOrderTraversal(self, root = 0):
        if root == -1: return
        print(self.keys[root], end = " ")
        self.preOrderTraversal(self.lefts[root])
        self.preOrderTraversal(self.rights[root])

    def postOrderTraversal(self, root = 0):
        if root == -1: return
        self.postOrderTraversal(self.lefts[root])
        self.postOrderTraversal(self.rights[root])
        print(self.keys[root], end = " ")

tree = TreeOrder()
tree.read()
tree.inOrderTraversal()
print("")
tree.preOrderTraversal()
print("")
tree.postOrderTraversal()

Above is some Python code that I’ve written - again, don’t worry if you don’t know what it does (i.e., the goal isn’t to learn new Python, though I’d be happy if you did).

However, the line of code I commented is faulty - the .split() method takes in a non-empty argument (e.g., a non-empty string). Hence, my code - as it is - will fail for this reason.

Had I caught this early on, I likely wouldn’t have been met with such a surprise when I tried to execute it (i.e., imagine what would happen if my code was any more complex - it would likely fail and I would have a way tougher time trying to find the bug)!

For this reason, you should always test your code from time to time. This isn’t to say that you should test your code every time you finish a line, but that perhaps after you finish a function or a block of code that does something, that you should probably test it out with a few test (and even edge cases)!

Don’t let your ego get the better of you (especially if you’ve worked with Python before)

I am admittedly guilty of this mistake from time to time. I’ve worked with Python before for data science (long before BS1009) and am currently studying web development with Python (i.e., learning how to use Flask and perhaps create a side-project with it) - put simply, I’ve done Python before BS1009 came around!

For this reason, I have a tendency to make my code as condensed as possible using list comprehension and dictionary comprehension, anonymous functions, and other Python one-liners. Instead of writing this (pretty clear to understand):
```
for i in range(1, 11):
    if i % 3 == 0 and i % 5 == 0:
        print("FizzBuzz")
    elif i % 5 == 0:
        print("Fizz")
    elif i % 3 == 0:
        print("Buzz")
    else:
        print("Nothing")
```
I might have wrote this instead (harder to understand):
```
for i in range(1, 11): print("FizzBuzz" if i % 3 == 0 and i % 5 == 0 else "Fizz" if i % 5 == 0 else "Buzz" if i % 3 == 0 else "Nothing")
```
If you remember what I said about programming and how it is almost always never a solo-effort, you really don’t want this to happen to you or your team! Otherwise, good luck to whoever (perhaps even yourself) comes across the above block of code when they try to figure out what it does¹!

Personally, I find that it always helps to slow down and remind myself that it’s not about how much I know or how “showy” I can be, but how well I can work with others.

Of course, this is a trivial enough example, but one can definitely imagine how tough debugging or adding new features to an application would be if your wrote code like this!↩︎