To comment or not, that is the question
Recently I worked my way through the “Effective Unit Testing” book. A nice read, nothing too complex or difficult, but it is always good to read the opinions of someone who really put some effort into a certain topic. One point was the question if code should contain comments or not, mainly because comments can have a negative impact because they can be incorrect and misleading. So the proposed solution was to write code that does not require comments at all; write “self documenting code”.
In my current project I run into similar situations on a daily basis; my idea on how code should look differs from the most of the other developers. I see people writing tons of code without a single comment in them and declare them “self documenting”. The problem is that for some reason I do not seem to be able to get comfortable with that code, and I’m really starting to wonder if I’m getting old, and am missing out on the “new and improved way” of doing things. But I’m not one to accept that without an effort, so I gave it a shot.
Below is an example of a simple unit test. Please do not spent too much time on this, because it is the “before” example. But the test is ok, there is nothing technically wrong with it, it just can be written better.
public void testVerifyGroupThenAddClient() throws ValidateException { // group starts off not verified GroupCare assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId()); assertNull(assertGroupCare.getVerifiedAt()); // add client groupCareManager.addClient(groupCare, client.getData(), groupActivity.getData(), user); // group is not yet verified assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId()); assertNull(assertGroupCare.getVerifiedAt()); // verify the group groupCareManager.verifyGroupCare(user, groupCare); // assert that the group is verified assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId()); assertNotNull(assertGroupCare.getVerifiedAt()); // add new client groupCareManager.addClient(groupCare, client2.getData(), groupActivity.getData(), user); // group is no longer verified assertGroupCare = groupCareManager.findByObjectId(groupCare.getObjectId()); assertNull(assertGroupCare.getVerifiedAt()); }