Are Code Rules Meant to Be Broken?
Editorial note: I originally wrote this post for the NDepend blog. You can check out the original here, at their site. While you’re there, take a look at the NDepend’s code rules. Interested in me writing for your site? Get in touch through our content marketing business.
If you’ve never seen the movie Footloose, I can’t honestly say I recommend it. If your tastes run similarly to mine, you’ll find it somewhat over the top.
A boy from the big city moves to a quiet country town. Once there, he finds that the town council, filled with local curmudgeons, has outlawed rock music and dancing. So follows a predictable sequence of events as the boy tries to win his new town over and to convince them of the importance of free expression. You can probably hear his voice saying, “come on, Mr. Uptighterton, rules are made to be broken!”
Today, I’d like to explore a bit the theme of rules and breaking them. But I’ll move it from a boy teaching the people from American Gothic to dance and into the software development shop and to rules around a codebase.
Perhaps you’ve experienced something similarly, comically oppressive in your travels. A power mad architect with a crazy inheritance framework. A team lead that lectures endlessly about the finer points of Hungarian notation. Maybe you’ve wanted to grab your fellow team members by the shirt collars, shake them, and shout, “go on, leave the trailing underscore off the class field name!”
If so, then I sympathize and empathize. Soul crushing shops do exist, seeking to break the spirits of all working there. In such places, rule breaking might help if only to shake people out of learned helplessness and depression. But I’m going to examine some relatively normal situations and explore the role of rules for a software team.
Aug
29
By Erik Dietrich
Is There a Correct Way to Comment Your Code?
Category: Language Agnostic Tags: Clean Code, Comments, NDepend | 50 Comments
Editorial note: I originally wrote this post for the NDepend blog. You can check out the original here, at their site. While you’re there, take a look at all of the visualizations and metrics that you can get about your codebase.
Given that I both consult and do a number of public things (like blogging), I field a lot of questions. As a result, the subject of code comments comes up from time to time. I’ll offer my take on the correct way to comment code. But remember that I am a consultant, so I always have a knee-jerk response to say that it depends.
Before we get to my take, though, let’s go watch programmers do what we love to do on subjects like this: argue angrily. On the subject of comments, programmers seem to fall roughly into two camps. These include the “clean code needs no comments” camp and the “professionalism means commenting” camp. To wit:
And then, on the other side:
Things would probably go downhill from there fast, except that people curate Stack Overflow against overt squabbling.
Splitting the Difference on Commenting
Whenever two sides entrench on a matter, diplomats of the community seek to find common ground. When it comes to code comments, this generally takes the form of adages about expressing the why in comments. For example, consider this pithy rule of thumb from the Stack Overflow thread.
Jeff Atwood has addressed this subject a few different times.
And so, as with any middle ground compromise, both entrenched sides have something to like (and hate). Thus, you might say that whatever consensus exists among programmers, it leans toward a “correct way” that involves commenting about why.
Read More