8. March 2010 10:35
I'm writing this as I'm assisting an organization I've worked with frequently conduct a code review on a project they had purchased (from a CMMI Level 5 certified off-shore firm). I had no role in the original application or any of the functional requirements so mostly I'm just a second set of eyes here. One thing (or rather the lack thereof) is jumping out at me as I'm listening to the narration. Although the code is definitely well formated C# source, my eyes usually head right to the coders comments first, look at what they are saying they are doing, and following along with a copy of the design documents close at hand to make sure we are on track.
In this case there was little to focus on for code comments, there weren't any. A decent design document with UML models, good Use Cases and User Stories, just nothing to get from the class library name to what they were trying to do in terms of walking the reader through the logic or explaining the flow once you hit the source. Now some of you may say (as they did) that good code is "self documenting". Well to some extent that may be true, be it fails to answer a basic question I always try and answer when conducting or participating in a code review: what was the developer thinking when they wrote this?
Aside from the obvious issues of navigating fairly complex code, there is also the larger issue of maintaining a code base for code re-use. Additionally if you are using a project as a template for more junior developers to build from (as this organization was) well commented code is usually more value than any other form of documentation. If you are a lead developer on a project like this, staying with easy to follow design patterns should take precedence over gaining a little bit of performance (or showing off your coding skills). So how much is too much ? Personally, I'd rather error on the side of stating the obvious rather than taking a chance on loosing the audience. When in doubt, explain it, especially if you are introducing a new technique to the team.