4

My company has a fairly large software project (a couple million lines of code spread across many assemblies.) One sticking point we've consistently run into during code reviews has been with the use of shared classes. We have various classes in a shared assembly used for solving common problems that occur throughout our code. These classes might do things like formatting a name or exporting a file - operations that we need to repeat in various places throughout the program.

We frequently have to fail code reviews because programmers are not aware of the shared classes available to them, leading them to reinvent the existing class. For example, a programmer might not know that there is a class designed to export a file to our specifications, so they write their own more-specific version. This becomes even more of an issue if the shared class was created recently, and isn't used in too many places yet. More junior programmers spend a lot of time reinventing wheels while doing tasks that, with full knowledge of the shared assemblies, would have been relatively simple.

What are some techniques we might try for spreading knowledge of these shared assemblies? Typical code documentation seems insufficient here, since the issue is with knowing whether a class exists in the first place. Are there good ways to document shared assemblies that would allow programmers to quickly answer the question of "Does a class already exist in our code that does x"? What can we do when adding a new shared class to let developers know about the class and encourage its continued use?

5

Are the existing classes well-organized? If you look at any well-designed library, it's generally pretty easy to figure out whether a class or method exists to do something because the class either exists more or less where you expected it to be or it doesn't. On the other hand, lots of poorly-designed libraries aren't organized in a way that makes sense to people trying to use them which makes discovering functionality hard. If you have an object junk drawer of "miscellaneous utilities", for example, that's going to be very hard for people to find what they're looking for.

Are senior developers helping junior developers learn the code base or just throwing them to the wolves and catching things once the code has already been developed and is ready to review? If I'm going to assign a task to a junior developer, I would expect that if I know there are pieces of code that can be leveraged that I would mention their existence. It makes sense in the initial white-boarding of the solution that the senior developer mentions that the junior developer should use the new message-handling framework that just got promoted or that the file generation class already exists and just needs to be wired in.

Are developers and project managers picking up on early indications that wheels are being reinvented? If a junior developer gets a task that I expect to take a couple of days because 90% of the code is already written and the appropriate classes just need to be called and that developer estimates that it'll take him 2 weeks, that should indicate a strong possibility that the junior developer is planning to build wheels that already exist. When that sort of disconnect happens, it's useful to walk through why there is a divergence in estimates. As the code is being developed, status reports stand-up meetings, and general chatter can let you know that a developer is spending more time on something than he "should" which often indicates that they're reinventing the wheel. A senior developer that overhears a junior developer trying to work through a problem saving files ought to suspect that the junior developer isn't using the well-tested file saving class and offer assistance.

Beyond that, you can certainly generate additional documentation that helps people use your class library more effectively. A wiki that walks through common tasks and explains the way that you want those tasks handled in new development, for example, can be an excellent resource. My bias would be to look at the process improvements first simply because one more source of documentation in an environment that has issues with the development process tends to become one more thing that gets out of date once the initial enthusiasm abates. But if you're doing everything you can from a process standpoint, the additional documentation can be very helpful.

0

Apart from the 'design your libraries well and put them in a logical location where people would expect them', reviewing is in fact a way of sharing knowledge. The earlier the review by more senior developers, the better. Have you considered pair programming? It's great for quickly sharing lots of knowledge about coding, design and domain. It is, in fact, a very early review.

Not the answer you're looking for? Browse other questions tagged or ask your own question.