DaedTech

Stories about Software

By

Is There a Correct Way to Comment Your Code?

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:

Chances are, if you need to comment then something needs to be refactored. If that which needs to be refactored is not under your control then the comment is warranted.

And then, on the other side:

If you’re seriously questioning the value of writing comments, then I’d have to include you in the group of “junior programmers,” too.  Comments are absolutely crucial.

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.

Good programmers comment their code.

Great programmers tell you why a particular implementation was chosen.

Master programmers tell you why other implementations were not chosen.

Jeff Atwood has addressed this subject a few different times.

When you’ve rewritten, refactored, and rearchitected your code a dozen times to make it easy for your fellow developers to read and understand — when you can’t possibly imagine any conceivable way your code could be changed to become more straightforward and obvious — then, and only then, should you feel compelled to add a comment explaining what your code does.

Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.

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

By

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.

Read More

By

Things Everyone Forgets Before Committing Code

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 around at some of the other posts as well.

Committing code involves, in a dramatic sense, two universes colliding.  Firstly, you have the universe of your own work and metaphorical workbench.  You’ve worked for some amount of time on your code, hopefully in a state of flow.  And secondly, you have the universe of the team’s communal work product.  And so when you commit, you force these universes together by foisting your recent work on the team.

In bygone years, this created far more heartburn for the average team than it does today.  Barbaric as it may seem, I can actually remember a time when some professional software developers didn’t use source control.  A “commit” thus involved literally overwriting a file on a shared drive, obliterating all trace of the previous version.  (Sometimes, you might create a backup copy of the folder).  Here, your universe actually kind of ate the team’s communal universe.

More Frequent Commits, Fewer Problems

But, even in the earliest days of my career, lack of source control represented sloppy process.  I remember installing the practice in situations that lacked it.  But even with source control in place, people tended to go off and code in their own world for weeks or even months during feature development.  Only when release time neared did they start to have what the industry affectionately calls “merge parties,” wherein the team would spend days or weeks sorting out all of the instances where their changes trampled one another’s.

In the interceding years, the industry has learned the wisdom of continuous integration (CI).  CI builds on the premise, “if it hurts, do it more,” by encouraging frequent, lower stakes commits.  These days, most teams commit on the order of hours, rather than weeks or months.  This significantly lowers the onerousness of universes colliding.

But it doesn’t eliminate the problem altogether, even in teams that live the CI dream.  No matter how frequently you do it and how sophisticated the workflows around modern source control, you still have the basic problem of putting your stuff into the team’s universe.  And this comes with the metaphorical risk of leaving your tools laying around where someone can trip over them.

So today, let’s take a look at some of the most common things everyone forgets before committing code.  And, for the purposes of the post, I’ll remain source control agnostic, with the parlance “commit” meaning generally to sync your files with the team’s.

Read More

By

Static Analysis Issue Management Gets a Boost

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, have a look at the features in NDepend’s latest version.

Years ago, I led a team of software developers.  We owned an eclectic portfolio of software real estate.  It included some Winforms, Webforms, MVC, and even a bit of WPF sprinkled into the mix.  And, as with any eclectic neighborhood, the properties came in a variety of ages and states of repair.

Some of this code depended on a SQL Server database that had a, let’s just say, casual relationship with normalization.  Predictably, this caused maintenance struggles.  But, beyond that, it caused a credibility gap when we spoke to non-technical stakeholders.  “What do you mean you can’t give a definitive answer to how many sales we made last year?”  “Well,” I’d try to explain, “I can’t say for sure because the database doesn’t explicitly define the concept of a sale.”

Flummoxed by the mutual frustration, I tried something a bit different.  Since I couldn’t easily explain the casual, implied relationships in the database, I decided to do a show and tell.  First, I went out and found a static analyzer for database schema.  Then, I brought in some representative stakeholders and said, “watch this.”  With a flourish (okay, not really), I turned the analyzer loose on the schema.

While they didn’t grok my analogies, the tens of thousands of warnings and errors made an impression.  In fact, it sort of terrified them.  But this did bridge the credibility gap and show them that we all had some work to do.  Mission accomplished.

Static Analyzer Issues

I engaged in something of a relationship hack with my little ploy.  You see, I know how this static analyzer would behave because I know how all of them tend to behave.  They earn their keep by carpet bombing your codebase with violations and warnings.  Out of the box, they overwhelm, and then they leave it to you to dial it back.  Truly, you can take this behavior to the bank.

So I knew that this creaky database would trigger thousands upon thousands of violations.  And then I just sat back waiting for the “magic” to happen.

I mention all of this to paint a picture of how static analyzers typically regard the concept of “issue.”  All categories of severity and priority generally roll up into this catch-all term, and it then refers to the itemized list of everything.  Your codebase has issues and it has lots of them.  This is how the tool earns its mind share and keep — by proving how much it can surface, and then doing so.

Thus you might define the concept simply as “all that stuff the static analyzer finds.”

Read More

By

Pulling Your Team Through a Project Crunch

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, download NDepend and take it for a test drive.

Society dictates, for the most part, that childhood serves as a dress rehearsal for adulthood.  Sure, we go to school and learn to read, write, and ‘rithmetic, but we also learn life lessons.  And these lessons come during a time when we can learn mostly consequence-free.

During these formative years, pretty much all of us learn about procrastination.  More specifically, we learn that procrastination feels great.  But then, perhaps a week later, we learn that procrastination actually feels awful.  Our young brains learn a lesson about tradeoffs.  Despair.com captures this with a delightfully cynical aphorism: “hard work often pays off after time, but laziness always pays off now.”

The fact that we laugh at this indicates something interesting.  Whereas we learn most childhood lessons and internalize them (e.g. don’t touch a hot stove), we don’t learn all of them this way.  Procrastination falls into this latter category.  We learn its perils, but we do it anyway, for various reasons.

As someone in the software industry, I suspect you can appreciate this.  Even if you diligently get out in front of all of your work, your organization may not follow suit.  So I’m sure you’ve seen your fair share of so-called “crunch time” over the years.  Crunch time occurs when you put a disproportionate amount of effort right before an important milestone.  Kinda like waiting until the night before the due date to write a 10 page essay on To Kill a Mockingbird.

Today, I’d like to talk about surviving these crunches.  How can you navigate them to come out on the other end with your team’s morale intact?

Beware the Death March

For argument’s sake, I’ll draw a fine line.  Crunch time and the so-called “death march” can seem like the same thing, but I submit that they differ importantly.  Crunch time involves working hard in a spurt to succeed.  Death marches involve working hard indefinitely with a high probability of failing anyway.

The first step for pulling a team through a crunch is to ensure that you’re not instead dispatching them on a death march.  If your organization has the unfortunate habit of getting itself into death marches, you have serious problems on your hands that transcend the immediate future.  At an organization like this, I’d recommend looking for escape avenues and hinting to others that they might do the same.

If this sounds bad or like the height of disloyalty, I suggest a bit of perspective.  Your organization is about to ask you to burn yourself out on an indefinite timeline for something that will probably fail.  Unless you’re a masochist, what about that warrants your loyalty?

Read More