Why bother with code formating

Not too long ago, I had a difference-of-opinion with another developer.  This developer is really good at what she does and has tons of respect from her colleagues and me.  However, we differ on our opinions for this topic.  Code formatting has a specific purpose and value.  If you are not targeting the value, you are missing the big picture.

I know I can seem unnecessarily rigid on some things, like code formatting and adhering to standards.  When I “L33t-up” on someone, about coding conventions/standards, it usually begs the question: Why?  Why does this sort of thing matter?  And does it/should it even matter?  Perhaps this is just me being pedantic or pushy to feel superior or some such crap.

Let’s start with: Why does code formatting matter at all?  Why not just write your program on one line with semicolons separating each statement, using variable names like x or i?  If you have ever looked at the code for jquery.min.js, it is an excellent example of this style of programming.  Maybe we should all write code like that.  Is this the key to producing something as popular as jQuery?!

Here are some reasons for formatting your code:

  1. It is more readable
  2. It shows attention-to-detail
    (I can stop now.  There are more reasons, but these two should be enough for anyone)

So for starters, let’s break-down #1.  You are probably aware that there have been numerous studies, over the years, on the topic of readability.  Newspapers started this field of study. Hence the width of the columns of text in a newspaper, and choice of font.  When computers were first becoming popular, researchers found that amber monochrome monitors were better than green-on-black because amber monochrome caused less eye fatigue.  This science has been re-hashed with the internet (fonts again, and active light source vs reactive, information density, etc.).

Similar studies have been done with coding, but most programmers don’t bother to familiarize themselves with this information.  It doesn’t impact their pay or reviews, so why bother?  Well, it should matter to the guy who is paying the programmers.  Studies have shown that some coding practices actually do increase readability and productivity.  So, a quality boss, should encourage/enforce these standards to gain greater efficiency from his team.  Otherwise, it is basically just wasted money or money that you could have picked-up but you just said “no thanks” and walked right by it.

If you are a person who cares about value and productivity, here is a list of things that can increase the readability of code:

  • Indenting
  • Capitalization
  • Consistency in all aspects of coding
  • Comments
  • Code coloring (now automatically performed by most dev tools, except for Notepad.exe or VI/Emacs on Telnet)
  • Punctuation (if your language du-jour uses braces or parentheses)
  • Modular or Object-Oriented programming (using functions and classes to arrange your code)
  • Naming conventions

In contrast, here are some examples of ways that might seem to help, but are actually doing the opposite

  • Overuse of comments – Peppering your code with useless comments will diminish the value of useful comments, as they disappear into a sea of noise.
  • Excessive partitioning of code – Overdoing it with functions, OO, inheritance, polymorphism to the point where it adds complexity and fragments logic,  will result in reduced readability.
  • Indenting as artwork – Commonly done by people with OCD: the code is aligned in nice geometric patterns with no further logical reason to do so.  People with OCD find this soothing and organized, but everyone else finds it to be disruptive because the geometric patterns will inconsistently define regions, blocks and segments of code that don’t go together logically. It is very counter-productive, but it sure does look nifty.

If you have been programming long enough, you have probably seen the worst that people can do with code formatting.  After you’ve seen the worst, then ordinary bad stuff seems somewhat trivial.  Moreover, most of us have enough fortitude, that we can overcome (or at least ignore) the misuse or non-use of these types of productivity habits.  So we tend to think, “Is it more work to badger my co-workers to conform, or is it less work to just MYOB and work-around the messes everywhere?”.  Certainly MYOB will seem like less work, every time you decide to take that route.  It is the path of least resistance.  However, walking around messes on the floor is not very elite and it is a job smell.  Is nobody going to be responsible enough to clean up this mess?  Not even you?  I don’t think that is true. I think we all just need a reason why.

There is value that is being left-on-the-table.  I would assert that a person does not need to be elite to format source-code well.  However, frequent demonstration of such excellence may lead to elitism.  No worries.  Please proceed.


About Tim Golisch

I'm a geek. I do geeky things.
This entry was posted in Methodology, Programming and tagged , , , , , . Bookmark the permalink.

2 Responses to Why bother with code formating

  1. gregsdennis says:

    I would like to submit an addition to your list of practices that help: vertical spacing. This usually goes toward the information density aspect you had mentioned.

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s