3 little, but important, things all programmers ought to do

Here’s my unsolicited advice to programmers serious about contributing to their development team.

1. Don’t be a renegade hacker when you’re at work

If you just learned about the Java ternary operator, use it by all means and as much as you like…. where it makes sense!

But, if you find yourself nesting ternary operators, that may be a sign you’ve gained some level of expertise at it. It may also be a sign that you are unnecessarily introducing difficult-to-read code for the rest of your team.

But it’s so cool!

Yup, but spare your colleagues the pain. Start your own pet project on github and knock yourself out with all the ninja syntax you can conjure up. And for all you know, you will attract like-minded coders. But work is not the avenue for it. If your team is building multi-tiered applications, there should be enough complexity as it is. You don’t want to be the reason for folks expending time understanding the minutiae of your code.

2. Format your code

Almost all IDEs make it easy to format your code. For instance, Eclipse gives you the Ctrl+Shift+F shortcut. If your team has code formatting standards, then follow it using a shared code format template.

I don’t use IDEs. I’m happy with vim.

That’s fine. Just make sure you go all the way in leveraging all the goodness that comes with the tool. vim, emacs and such come with a dizzying array of shortcuts/extensions/modes that you need to be familiar with.

What’s the big deal with code that is unformatted?

It is a HUGE deal. When all you want to do is review someone’s code to understand what it does, seeing poor indentation, out-of-whack braces or 400-character lines that you have to scroll through horizontally to get to all its parts, are all annoying distractions you can do without.

But if it’s that easy to format, why don’t you just format it when you review it?

I have been asked that once by a junior developer. Didn’t answer it then. Not going to answer it now. I will say this: you don’t need a very vivid imagination to come up with a nightmare scenario for this. And if you’ve experienced it first hand, you don’t need to use your imagination.

Remember:
Your code is a deliverable. It is an artifact. It will be examined and spoken of. It will be shared. You’d best spend some time  on it.

3. Put some thought into commenting your code

This is a bit subjective. But, suffice it to say the following is unhelpful.

// create product

AdminOrderProduct[] orderProducts = new AdminOrderProduct[1];
AdminProduct product = new AdminProduct();
int productId = 0;
product.setName(props
        .getProperty("product.placeholder.name.prefix")
        + referenceNumber);
product.setQuantity(10);
product.setUuid(new Date().getTime() + "-" + referenceNumber);
product.setStatus((byte) 1);
product.setWeight(BigDecimal.ONE);
product.setPriceIncTax(paymentAmount);
product.setPriceExTax(paymentAmount);
product.setWeight(BigDecimal.ZERO);

// save product

product.save();

All those two comments do for me is state the obvious. You could have safely eliminated them IMO.

That being said, here are a couple things I would be curious about from looking at that code snippet:

  1. Why is the AdminOrderProduct[] array of size one?
  2. Is there a business rule driving how that UUID is constructed? Or is that a random format you picked?

A couple lines of comments addressing the above would do a lot towards setting my mind at ease. Keep these in mind when commenting your code:

  • Don’t translate each line of code into English (assume your code is being read by a capable developer)
  • Address the why
  • Call out ramifications to external systems
  • Call out pre-conditions and post-conditions
  • Call out poorly written code even if (especially if) you wrote it. It makes for a much better case to refactor a code snippet if the code author is the first to believe something can be improved.

This (i.e. writing intelligent comments) is not as easy as it looks. That’s what makes it valuable. I still struggle with effectively commenting my code. It takes some degree of stepping back and thinking. But it is possible. And it will pay dividends.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s