The challenges of using and reading other peoples' code

I recently came across this post by Phil Haacked, and it's very worth reading and thinking about...

I completely agree with the the point that "reading code is hard" in this big world... Especially when everyone follows different styles things for things like naming, organizing code and designing systems...

Another way of making code easier to read that Phil didn't mention and that I really like to use (and many other people like to use too) is by writing developer tests with a testing framework (any member of the xUnit family for instance...). Not only will they help you get your code "right"/working, but someone who wanted to see what your code can do can look at your tests (or write their own) to figure out what your code actually does. To me, the underlying qualities of unit tests that facilitate this are:

• in a test, you have to explicitly create the immediate environment/context in which your code will be interacting with - in OO terms, this is in terms of the state of your objects and their collaborators
• the interface for executing the test is standardized - you pretty much only have to learn once where to put a test so that it is recognized by a test execution tool...
• writing tests with the intention of running them sort of forces you to write somewhat testable code
  

I don't think developer tests are silver bullets since they can be overused and misused, but I think they can help in a number of ways, including helping to address things like readability.

I think another point worth mentioning is that code that is written not following good coding practices and that has bad code smells (such as long methods, cryptic variable names, etc) will be harder to read - I believe Phil received enough feedback that led him to link to this post on the topic.