How to promote code reuse and documentation? [closed]

Question

As a team lead of about 10+ developers, I would want to promote code reuse. We have written a lot of code-- a lot of them are repetitive over the past few years. The problem now is that a lot of these code are just duplicate of some other code or a slight variation of them.

I have started the movement ( discussion) on how to make code into components so that they can be reused for the future projects, but the problem is that I afraid the new developers or other developers who are ignorant of the components will just go forward and write their own thing.

Is there anyway to remind the developers to reuse the components/ improve the documentation/ contribute to the underlying component instead of duplicating the existing code and tweaking on it or just write their own?

How to make the components easily discover-able, easily usable so that everyone will use it?

I think every developer knows about the benefit of reusable components and wants to use them, it's just that we don't know how to make them discoverable. Also, the developers when they are writing code, they know they should write reusable code but lack of the motivation to do so.

Answer 1

You need documentation, a proper one. It should be easy to find and navigate. You also need discipline. If there's already a solution provided in your reusable code libraries but the developer chooses to use his own solution instead (without any proper reason), you should revert his solution and tell him to use the existing solution.

I also agree with Euphoric's comment to the question. It's often impossible to reuse anything between different projects (usually all the CRUD operations look the same, but usually you can't reuse them).

Answer 2

Beside the already mentioned factors "documentation", "easy to find and navigate", "discipline" and "codereview"

resusable code must be

• easy to use (= need examples i.e. unittests)
• without too many dependencies to other modules and
• it must have a stable api so i donot have to update my aplication to use the library.

without the last two items it is much easier to use "copy&past-inheritance" that we do not want.

Answer 3

I think the best way to actually make them reuse code is motivation. If you put the reusable components in extra projects, like Euphoric suggested, put much effort in it. Where I work, we made a project, that runs a set of predefined interfaces in configurable executionplans and provides a few services (e.g. different classes for DB_interaction, an FTP-Service, ...). The project is a big success, because our developers actually want to use the micro-framework, because it is saving them a lot of time for writing boilerplate-code for similar projects. The same thing is for Utility-libraries for Lists, Strings, etc., but in this case you would want to use existing once. (why reinvent the weel?)

Conclusion: Let your developers experience the benefits of well-tested reusable components. But I also agree with the answer of Andrzej Bobak: Many things aren't reusable, because they are similar, but not the same.

Answer 4

This is going to be difficult, because people like to write new code for simple components and they like doing it their way. It's much harder to leverage an existing solution and extend it, than to write a completely new implementation with the new requirements. What you need to do, as has been stated, is start a code review process among the team to help identify situations where an existing components should have been used/extented instead of a new one.

You also need to maintain a very good and thorough documentation so that people can refer to it and easily find what they need. If the documentation is incomplete or out of sync with the real thing, people will not be motivated to search through it or enhance it.

As the team lead, you should also encourage people to ask themselves if a similar component exists before creating their own and direct them to the documentation so they can look it up. Sure the code review process will catch it if someone missed an existing component, but what if they already put 10 hours of development in their own implementation? You need to avoid these situations by enforcing good research behavior in the team.

Answer 5

We've faced this problem on a big project I'm currently working on. We've had some rotation of developers over the last few months, it's also quite a large code base and even the ones who have been on the project since the very beginning don't know every inch of it.

While the code is often well-written and split into small parts with single responsibilities and the documentation is there, it's quite easy to miss something that has been done. Consistent naming conventions help a lot because it's easy to look something up in any IDE. Documentation may be comprehensive but as it grows longer, it's a bit of a pain to read through it.

One thing we did that, in my opinion, improved the situation greatly was the introduction of a thing we call Lightning talks. Whenever someone writes a piece of code that he or she believes should be known to the team, a short (usually 5-15 minutes) presentation is arranged. We try to do this once every week. The subjects tend to vary, from new features and ways of handling complex problems that have recently come up, through testing/coding approaches, reusable component, to talks about the foundations of the app and refactoring thereof.

Certain subjects are mentioned on similar, company-wide talks. We've found it a pretty efficient ways to spur knowledge sharing. It's much easier to see and remember a short presentation and know where to look for additional documentation or whom to address for help than to participate in very long and rarely held training sessions or to just sit there, reading the docs cover to cover.

The company-wide talks actually came first. We just adopted this approach for project-specific knowledge sharing and I think it's working pretty well.

Pair programming also makes the knowledge circulation a lot faster.

Answer 6

I think that this is actually two questions in one - I'll try to answer both.

1) How do we reduce duplicate code in a codebase.
It helps to remind ourself of the benefit of doing this: it results in fewer bugs due to duplicate business logic and less code needs to be maintained. The best way to reduce this from happening is through communication - as mentioned in the other answers. I'd strongly agree with the recommendation to use code reviews with the extra caveat that you should share code reviewing responsibilities equally to properly spread the knowledge. You should also use daily stand-ups so that developers will often recognise when someone is trying to solve a problem for which there is existing useful code. You should also consider code pairing as it increases knowledge sharing and helps to keep programmers disciplined.

I'd also recommend getting your developers as close together as possible, preferably in the same room. With lots of shared whiteboards and space. Then send them out for meals together. The more your developers "bond" the better they'll communicate with each other.

I don't agree with the recommendation to use a wiki or similar to document code. No matter how disciplined developers try to be the documentation will drift from the original code. A more effective approach would be the use of specification by example style tests. These document the code in a way that makes it clear how it should be used and your tests will fail if someone changes the code without changing the examples.

You already have a large codebase with lots of duplicate code so you should probably work on refactoring this out. It can be difficult to find duplicate code that wasn't cut and pasted. So rather than do that I suggest you analyse your change history. Look for files that often change at the same time. This will probably indicate problems with encapsulation if it doesn't indicate actual duplicate code and is worth cleaning up anyway. If you can also analyse your bug fix history against your code changes you may find particular hotspots where fixes are often necessary. Analyse these hotspots and you'll probably find many of them are due to duplicate business logic which a developer has only changed in one place not realising it needed changed twice.

2) How should we approach making shared widgets, components, libraries, etc that can then be used in other projects.
In this case you should not be trying to wrap business logic but share useful framework code. This can be a tricky balance as the cost of creating and maintaining a set of shared components can be quite large and it can be difficult to predict in which instances it is worth doing. The approach I'd suggest here is a three strikes rule. Don't worry about writing a similar piece of code twice but when you need to do it a third time refactor it into a shared component. At this point you can be reasonably sure it will be useful and you have a good idea of the broader requirements for the component. Obviously, communication between developers is vital here.

Consider making as many of your shared component open source as possible. It isn't business logic so it won't give your competitors much advantage but it means you'll get extra reviewers and maintainers for free.

Answer 7

IMMO the key its not documentation or tools, the key is COMMUNICATION. 10+ developers its not a lot of people, some things that improve this communication:

• pair programming: with two people there are more changes that one of the two knows that the problem its already solved in another part of the project and reuse it.

• Collective code ownership: All the people works with the different parts of the systems, this way its much easier that they know that something its already done in another part of the project, for me this is fundamental practice in a team.

• Give time to work of horizontal projects: for example, one friday or two in a month, and the developers in this time can work in his own projects that has some applicability to your company project. This way the developers can write reusable libraries and components, sometimes its code thats already exists but need some cleaning and documentation.

• Make talks and workshops: Reserve a time for developers talks and workshops, the developers can talk about his libraries or perhaps you can do refactor workshops and take some duplicated code and remove the duplication creating a reusable component.

Documentation probably its needed but its only a small part of the real thing you need: improve the communication inside your team.

Answer 8

What about using a local search engine such as Lucene (or something more specific to source code) to index your code? When someone starts writing a new class or a new function (for example) he must try (as internal policy) a couple of searches before writing his own code. This way you can avoid too much communications and you can rely on good comments, methods and classes names. I find myself doing this with open source search engines available on internet: I don't know who wrote what or what is the name of a method or a class, but with a couple of searches or synonyms I always find what I need.

Answer 9

You need a tool that helps your developers to do it in a seamless way. If your developers discover how much time they can save by reusing the code snippets (not only in terms of writing the code, but obviously for quality assurance, integration, etc.), helped by an efficient tool that is easy-to-use and directly integrated into development environment, they will PRAY you to adopt such a tool!

Be careful that a lot of times the realization of libraries for code reuse will not result in a huge advantage (they tend to become too much powerful and large...); instead, I would like to focus on simple snippets, i.e. few lines of code that solve a particular task in an effective way.

In this way you can force the usage of guidelines and best practices by giving real examples that can be directly used by programmers.

There are several tools for the snippet management, I recommend this one: http://www.snip2code.com.

(Disclaimer: I'm one of the founder of Snip2Code, and I was - together with my co-founders - in your very same mindset some time ago: this is why we decided to start this project, which collects all the features that I stated above, i.e. sharing snippets among a team, integration in IDEs like Visual Studio, Eclipse, IntelliJ, Notepad++, etc.)