Wednesday, March 21, 2018

Comment Your Code

Most code is for developers, not for computers. Computers have always been perfectly capable of reading long streams of ones and zeros, performing work on those stream, then spitting out results as new streams of ones and zeros. Sure, computers have gotten faster since those streams were stored exclusively on paper punch cards. And sure, we now have new ways of providing input and receiving results. But, most computers still operate in the same fundamental way. Computers don't need C#, Ruby, JavaScript, SQL, JSON, compilers, interpreters, monitors, keyboards, mice or VR. People and developers do.

Most developers don't garner any meaning from reading a bunch of ones and zeros. Most people need abstractions in order to understand any significantly complex idea. And, people make more assumptions than they realize. These and similar human failings are why the vast majority of software language features exist.

To get around the lack of understanding of binary information, developers use higher level, abstract languages to create software. A good number of developers think their code is perfectly readable on its own. Even if that were the case, the only way to prevent others from making incorrect assumptions is to provide more context than the method calls themselves. This means commenting your code in plain [language of your choice] to describe the responsibility of each member.

Similar to how unit tests provide a second set of code to ensure correctness, providing another description in addition to the code itself will help prevent misunderstandings about how to use and maintain your code. Some people go so far as to claim that unit tests are an adequate replacement for comments. Bollocks. If your code doesn't take advantage of the popup guidance that intelligent code completion tools (IntelliSense to us Visual Studio fans) provide to instruct others on correct usage, you're not using the best tool available.

Other developers claim that commenting code takes too much time. But if an engineer can't type a description of the responsibility of a class, interface, property or method in under a 15 seconds, they either don't understand its responsibilities or they need to learn to type faster. Either is a deficiency in any engineer's professional skill set. Those extra seconds of typing may add up, but they are a tiny percentage of the time that should already be spent on designing, writing and testing that code. That time is also miniscule compared to the amount of time that will be prevented maintaining the documented code and fixing bugs when uncommented code is inevitably misused.