Tuesday, March 16, 2010

Developer Etiquette

I created a list of etiquette guidelines for Software Engineers.  These etiquette guidelines are not for social interactions, but are instead for writing code.  Like most etiquette guidelines these are designed to minimize the discomfort for others.  So here they are.

Before committing I will:

  1. Review the patch.
  2. Review the list of files that are not being committed, but have been modified or are new.
  3. Compile the code.
  4. Run any affected unit-tests.
  5. Test the code to make sure it does not break core functionality.
The reason behind #1 is simple.  It's very easy to accidentally commit code that's not ready, or that contains printf debug code.  It's quite obnoxious to have your terminal sprayed with hundreds of "XXX Hey I'm executing function foo()."  By following guideline number #1 you will rarely accidentally commit half-baked code.  The git add --patch command makes this really easy.

Guideline #2 saves you from forgetting to commit some critical patch, or more commonly forgetting to add a new file to the repository.  I've found that most of the time when code compiles on the developer's computer but not anyone else's, it's because they forgot to add a file.  The git status command helps here.

Guideline #3 is simple.  Committing code that doesn't compile turns a O(1) problem into a O(n) where n is the number of developers on your team.  Don't ever check in code that doesn't compile.

Guideline #4 ensures that you don't accidentally break the unit-tests.  It is much easier to fix bugs earlier rather than later.  So if you break the tests it's better to find out before you commit.

Guideline #5 is similar to #4 but assumes that not all of your code is covered by unit-tests.  Even if you test every line of code with unit-tests, your unit-tests won't tell you that you just made your GUI look like puke.  So run the code and make sure nothing broke.

If you follow these guidelines you can still write horribly broken code and be a terrible developer, but at least you won't prevent your co-workers from being competent.


  1. Nice guidelines.

    Sometimes right after committing, I quickly do a fresh checkout and clean build to make darn sure I didn't forget anything.