Senior Year as a CS Major

Winter 2024, the start of CS 462!

I chose to read this article on clean code
and this article on code smells.

What is one thing from the articles that you would like to start doing (more often), and why? What is one thing you want to avoid doing and why?

An area I always strive to improve in is applying comments strategically. I have vascillated (but, I think, improved overall) in my commenting style since I started going to school for Computer Science. In my lower-division classes, I developed really poor coding practices in that I rarely, if ever, actually commented. In part, this habit developed because the initial programs I was coding were so simple that they could easily be deciphered without comments, but because I didn’t correct this early on, it continued to my more complicated code. The code snippet below is an example from one of my early programming classes that could sorely use some commenting:

if (rr + rw >= 1)
{
   for (int i=0; i<set.size(); i++)
   {
      string temp = set[i];

      if (temp[0] != n1000 && temp[1] != n1000 && temp[2] != n1000 && temp[3] != n1000)
         set.erase(set.begin()+i);

      if (temp[0] != n100 && temp[1] != n100 && temp[2] != n100 && temp[3] != n100)
         set.erase(set.begin()+i);

      if (temp[0] != n10 && temp[1] != n10 && temp[2] != n10 && temp[3] != n10)
         set.erase(set.begin()+i);

      if (temp[0] != n1 && temp[1] != n1 && temp[2] != n1 && temp[3] != n1)
         set.erase(set.begin()+i);
   }
}

When I realized that this was an issue that really needed correction, I ended up overcorrecting and used comments a little excessively (a better problem to have, but a problem nonetheless). The following code snippet is an example from a later course with some truly unnecessary comments:

public class MonthDays
{
...
  //constructor for class
  public MonthDays(int month, int year)
  {
    setMonth(month);
    setYear(year);
  }
...
  //retrieves the month
  public int getMonth() 
  {
    return month;
  }
...
  //returns the year
  public int getYear() 
  {
    return year;
  } 
...
}

I feel like I’ve improved a lot in my commenting practices at this point. Functions and blocks of logic generally have a comment quickly explaining their purpose, non-obvious bug fixes have comments explaining why something needs to be a certain way to avoid repeat mistakes, and blocks of code with similar functionality will have one accompanying explanation comment. I know though, that I still tend to overcommenting and it’s something I actively try to be aware of and will continue to try to improve going forward.

A practice I would really like to avoid is long parameter lists (#9 on the code smells article for reference). I chose this because it’s honestly something I’ve never thought about before, but is something I’ve noticed in code I’ve used (like imported classes or skeleton code). I do think I’ve done a pretty good job of staying away from this in my own code naturally, but I’d like to be more cognizant in avoiding it intentionally going forward.

The article makes a great point that if your parameter list is too long, your function is probably doing too much. But for me, the biggest issue comes with usability. Long parameter lists make it challenging to use a function. The programmer has to consider too many things – “What order do these go in?” “Which arguments are needed for this call?” “What types are used for which variables (especially when looking at number types – is it a decimal, float, int, double)?” If I have to look at a function header 3+ times to get all the parameters in, it’s most likely too long to be practical.

As an example, the crosstab function in the pandas library is, in my opinion, challenging from a usability perspective because of the number of parameters used. Below is the function header, but here is the doc page for reference.

pandas.crosstab(index, columns, values=None, rownames=None, colnames=None, aggfunc=None, margins=False, margins_name='All', dropna=True, normalize=False)

These were some great examples of what to be more mindful of in my code, but reading through all of the other best practices on clean code and code smells were incredibly helpful as well. I think just having taken the time to think through all of these will make me more mindful in writing and reviewing my work.