In late October 2017, I went to the Full Stack Toronto (FSTO) conference. A talk given by Jane Prusakova, "Good Code: What, Why, and How," pointed out the issues in CS135, the first year computer science course many first year Math students take. While I may focus on CS135, the issues I point out may also be applicable to CS115 and CS145, and may even be more prominent in CS 115 compared to the other two courses.
In CS135, there is way too much of a focus on how you should be commenting code. This is a terrible practice and annoying part of every assignment. I remember spending more time on trying to have proper comments everywhere as opposed to actually coding. Right now, I can think of one real case where comments could be used and that is for TODO statements. In dynamically typed languages such as Python and JavaScript, you can leverage the static typing constructs by implementing libraries like mypy and PropTypes or TypeScript, respectively, into your projects. Thus improving the maintainability and readability of your code without the need of comments.
Programs must be written for people to read, and only incidentally for machines to execute.
-Abelson & Sussman, Structure and Interpretation of Computer Programs
I really like this quote because it is true, unless, of course, AI has taken over and replaced software developers. At work, I spent more time reading and debugging code, rather than writing new code. You have to first understand the code and data flow before you will be able to implement a bug fix, especially when you are thrown into a completely new framework and workflow that you've never touched before. However, this was not the case in CS 135 when I took it.
I remember looking at my assignments from the semester to review for my final exam and I did not understand my code at all after just months or even weeks of writing it. The act of enforcing a mandatory "design recipes", which were essentially comment blocks decorating each and every function, were more detrimental to my development as a software developer than if they did not include this requirement. These "design recipes", or comments, consisted of:
- Purpose: describes what a function does
- Contract: states the argument types and the returned value type
- Examples: self-explanatory
- Definition: the function signature but in a comment - yes, very redundant and a garbage practice
- Tests: set of function calls with expected return values
This resulted in the negative practice of avoiding helper functions all together and just creating a single function for each question. Honestly, this was fine for the first few assignments, but as we got farther into the semester and the assignment questions became more complex and my code got less and less readable. Practically all of my friends also did this. We didn't want to create more points of failures where we could lose additional marks just because we chose to create a few helper functions and made a few mistakes in the useless "design recipes." Rather than focusing on the "design recipe," they should have had more of an emphasis on code readability since a lot of my code was pretty atrocious, especially when considering the stupidly short line length limits that barely took up a third of my 13 inch Macbook Air's screen real estate. There were some pretty creative (heh, more like moronic) new line placement to fit each line of code within the specified length requirements.
I feel sorry for everyone that has and is going through this garbage. Come on UWaterloo, you're supposed to be one of the best but this course has way too much of a focus on undesirable industry-skills and you should know this very well. Shame on you for not improving this course even when we've called you out all those years ago...
