CodeThatDocumentsItselfSoWellItDoesNotNeedComments

“When I first met the lead developer at my new job, we had a very long and very good conversation about code quality,” Ben Stilgar wrote. “He and I just seemed to click, especially when it came to self-documenting code: architecture should balance functionality and understandability, program flow should be optimized only after performance problem, and code should be clear and understandable, even if it takes longer to write.”

“You can imagine my excitement when it came time to opening The System, which was the lead developer’s masterpiece and culminated over a decade of design and development experience into a clean, almost-perfect application. You can also imagine my disappointment when I finally dived in and learned exactly what he meant by self-documenting code.”

switch (mIntegrationDirection)
{
   case InventoryIntegrationDirection.DoTheSameChangeInShop:
      DoTheSameChangeInShop(GetChangedDataFromInventory(mLastSynchDate));
      break;

   case InventoryIntegrationDirection.DoTheSameChangeInInventory:
      DoTheSameChangeInInventory(GetChangedDataFromShop(mLastSynchDate));
      break;

   case InventoryIntegrationDirection.DoTheSameChangeInShopThenDoTheSameChangeInInventoryForNotChangedDataInInventory:
      DoTheSameChangeInShopThenDoTheSameChangeInInventoryForNotChangedDataInInventory(
	   GetChangedDataFromInventory(mLastSynchDate), 
	   GetChangedDataFromShop(mLastSynchDate));
      break;

   case InventoryIntegrationDirection.DoTheSameChangeInInventoryThenDoTheSameChangeInShopForNotChangedData:
      DoTheSameChangeInInventoryThenDoTheSameChangeInShopForNotChangedData(
	   GetChangedDataFromShop(mLastSynchDate), 
	   GetChangedDataFromInventory(mLastSynchDate));
      break;

   default:
      break;
}

Ben added, “when the lead developer asked for my feedback, I gritted my teeth and smiled, doing my best to compliment-but-not-compliment the design. He responded, ‘and the best thing is, with code like this, there is no need to write a single comment, anywhere.’ I’m not sure if there wasn’t a need to have comments… but I can say that there wasn’t a single comment, anywhere.”