Recent Representative Line

A single line of code from a large application that somehow manages to provide an almost endless insight into the pain that its maintainers face each day.

Aug 2016

Accuracy in Comments

by in Representative Line on

Comments are rough. I always take the stance that code should always be clear enough to explain what it does, but you’ll may need a comment to explain why it does that. I recently attended a talk by Sean Griffin (maintainer of Rails) who argued that commit messages should accomplish that goal, since they can contain far more content than a code comment, and while code comments and code can drift apart and cease to be accurate, commit messages are always linked to the point-in-time when they were made. Donald Knuth, on the other hand, might argue that code should annotate comments instead of the opposite.

Regardless of the method we use, I think most of us would agree that code needs some documentation in the same way it needs tests: it should exist, but we don’t want to have to create it.

Compatibly Backward

by in Representative Line on

I took my first official programming class circa 1997, and that year was notable, only because it was the last years that class was taught using Turbo Pascal. In future years, it was taught in C++. For the teacher, this was quite the transition. To help her make the transition, at the end of the course, she spent a few days teaching us basic C++, so she’d be more ready for the following class, and we got a little bonus education.

As far as I know, future runs of the class went just fine. I bring this up, because Frank had some co-workers who needed to make the exact same transition, from Turbo Pascal to C++. They may have done it a bit less gracefully. When reviewing some of the C++ they wrote, Frank spotted lots of code like: