Mini-blogpost in response of a twitter correspondence

CalculatorTest.java

/**
 * Disclamer: This is sort of a rant, but without any negative feelings towards the creators of the project
 * in question.
 * I value their desire to help people write more readable code, and wish there were more people doing this!
 * The only thing I'm questioning is the ever growing trend of tools over craft.
 * 
 * This is a mini blog-post in response to https://twitter.com/hhariri/status/435457449232171008
 * 
 * The reason I have some negative feelings is that writing readable code is not rocket
 * science, and with tools like Spek, we're basically allowing people to be ignorant about crafting clean
 * code.
 * 
 * I'm not particularly happy with the pretense of the project, as the code used is indeed unreadable.
 * I however don't see the solution in masking that unreadability by yet another tool, but in refactoring
 * the code to make it self-documenting.
 * 
 * With Spek, we create instant duplication of the code, in the comments. What happens if you change the
 * income value or the expected outcome? You don't only have to change them in the test code, but the comments
 * too.
 * 
 * Let me quote the project readme:
 * 
 * "Tests are specifications
 * Tests are executable specifications of your system. They are real-time compilable code that tell you how
 * a piece of code should behave and under what conditions is a certain outcome expected. That is why it is
 * important to be explicit, concise and unambiguous when it comes to defining specifications."
 * 
 * My point exactly!
 * 
 * So without further ado, here's my version of the test in question.
 * To be fair to the project, I haven't modified the interface of the TaxRateCalculator, although I would
 * happily rename calculateRate() to rateOfIncome().
 * 
 * @author meza www.meza.hu
 */
public class CalculatorTest {

	@Test
	public void testCalculateTaxRate() {

		TaxRateCalculator calculator = new TaxRateCalculator(TaxRateCalculator.DEFAULT_LOCALE);

		int income = 200;
		int averageChangePerSemester = 10;

		int actualRate = calculator.calculateRate(income, averageChangePerSemester);

		int expectedRate = 300;

		String messageOnFailure = String.format(
			"The rate for an income of %d was not calculated correctly for an average change of %d per " +
			"semester", income, averageChangePerSemester);

		assertEquals(messageOnFailure, expectedRate, actualRate);
	}

}

I'm interested in this idea but I'm not sure I understand the notion of where the domain knowledge should "go", and how domain knowledge can be effectively communicated to developers new to a codebase. Would this level of domain specification not be expressed in the tests? If the developer is following a TDD cycle then the refactoring steps should have introduced appropriate abstraction in both the tests and the implementation? OCP, SRP, and ensuring there is no duplication between the tests and the implementation code should get us to this result. We should be left with test code that fully specifies the implementation, or am I missing something?

Regarding the discoverability of specifications where they are kept apart from the implementation, your codebase should be fully navigable in most modern IDEs.