Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

When working on code, I face many of the same challenges that my teammates do, and I have written some helpful functions and classes, and so have they. If there is good communication, I'll hear about some great thing someone put together, and six months later when I need it I may remember it and call that function, saving myself time. If I don't remember it, or never knew about it, I will probably re-invent the wheel.

Is there a particular practice of documenting these kinds of things? How do you make them easy to find?

If your team has no such documentation, how do you find out if your wheel already exists?

EDIT:

All but one of the answers so far deals with an ideal situation, so let me sum up those solutions: documentation & communication; wikis, stand-up meetings, etc. Those are all great things, but they rely on programmers having the time (and skills) to write up the documentation and attend the meetings and take notes and remember everything.

The most popular answer so far (Caleb's) is the only one that could be used by a programmer who is incapable of documentation and meetings, and does only one thing: programming. Programming is what a programmer does, and yes, a great programmer can write up documentation, unit tests, etc., but let's face it - most of us prefer programming to documenting. His solution is one where the programmer recognizes re-usable code and pulls it out to its own class or repository or whatever, and by the fact that it is isolated, it becomes find-able and eases the learning curve for using it.... and this was accomplished by programming.

In a way I see it like this: I've just written three functions, and it occurs to me that someone else should know about them. I could document them, write them up, announce them at a meeting, etc. - which I can do, but it's not my strength - or .... I can extract them to a class, name it well, make them function like a black box, and stick it where other class files go. Then a short email announcing it is easy. Other developers can scan the code and understand it better than they could an isolated function used in code they don't fully understand - that context is removed.

I like this because it means having a set of well-named class files, with well-named methods, is a good solution that is accomplished by good programming. It does not require meetings, and it softens the need for detailed documentation.

Are there any more ideas in this vein ... for isolated and time-pressed developers?

share|improve this question
4  
I would expand the question to ask on a larger scale, perhaps in a company of 100+ employees how do you do the same. What best practices can be done to avoid duplication of previously done work? –  Asaf Apr 30 '13 at 14:41
1  
@Asaf - I suspect the correct answer would depend on the size of the population - what works for a 5 person shop won't work for 50, and what works for 50 won't work for 500. Answers to all would be welcome. –  Dan Pichelman Apr 30 '13 at 14:57
3  
This is a great question! –  LachlanB Apr 30 '13 at 14:58
4  
Conway's Law: "organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations". –  Mark Rushakoff Apr 30 '13 at 15:15
2  
@nathanhayfield: that's a solution that may work for 1 dev, and to some degree for 2, but not for 20 or 100. And even when I work alone, I prefer separating helper functions thematically. –  Doc Brown Apr 30 '13 at 19:29

7 Answers 7

up vote 30 down vote accepted

Libraries. Frameworks. Version control.

If you've got reusable code, the very last thing you want is for different team members to copy the source code into their project. If they do that, chances are that they'll change a bit here and tweak a bit there, and soon you've got dozens of functions or methods that all have the same name but which each work a little bit differently. Or, perhaps more likely, the original author will continue to refine the code to fix bugs, make it more efficient, or add features, but the copied code will never get updated. The technical name for that is a huge freakin' mess.

The right solution is to pull that reusable stuff out of whatever project you built it for in the first place and put it into a library or framework in its own version control repository. That makes it easy to find, but also discourages making changes without consideration for all the other projects that might be using it. You might consider having several different libraries: one for well-tested code that's no longer likely to change, one for stuff that seems stable but which hasn't been thoroughly tested and reviewed, one for proposed additions.

share|improve this answer
5  
I'd also like to recommend having a very thorough set of regression tests for the reusable library. Even if the change seems harmless, someone might be depending on that behavior. –  Bobson Apr 30 '13 at 16:29
2  
I thought the technical term was BBOM. –  zzzzBov Apr 30 '13 at 16:59
2  
Your answer sounds reasonable at a first glance, and on smallr to mid-size scale it is, but I have also seen the dark side of a "don't copy" directive. If you have different teams for different products, with different license terms, different life cycles and different maintenance contracts, the very last thing you want is to couple the different products to a home-brewn library of code snippets which does not match that maintenance requirements. Libraries for that kind of scenario need to have very high quality, and sometimes its even more effient for a team to copy the code and .. –  Doc Brown Apr 30 '13 at 19:11
3  
@Caleb: keep calm, read my posting completely. My point is: copying code frome somewhere else, tweak it and integrate it into a teams library does not necessarily bring you on the "road to perdition". When you have two libs with overlapping functionality, and two teams from which each is responsible for maintaining their lib, the situation is not that bad. That's not perfect, since one team may do some work the other one does, too, but sometimes the advantage that those teams keep beeing independent outweighs the double work. –  Doc Brown Apr 30 '13 at 19:48
1  
@DocBrown There are situations in which it becomes necessary to copy code, but that should be a conscious decision and not something that you're forced to do because of the manner in which the code was shared in the first place. –  Caleb Apr 30 '13 at 20:07

One approach for that is setting up a Wiki for that purpose, and write some high-level docs on what reusable components you have, how you solved a problem etc.

The hard part is to get every one in your team to constantly maintain that Wiki. But any other kind of documentation suffers from the same problem.

Some of your code may also be good enough to be put into a reusable library. This makes it also easier to find the code again later.

share|improve this answer
5  
A wiki is not the right way to disseminate code. It's a great way to communicate about code, but (see my answer) you don't want people copying anything larger than a snippet out of a wiki and pasting it into their project. –  Caleb Apr 30 '13 at 15:19
    
@Caleb the communication is the hard part –  jk. Apr 30 '13 at 15:58
    
@jk - The problems of communication are compounded if you don't have the source control mentioned in C –  JeffO Apr 30 '13 at 18:09
3  
@Caleb: the OP's question was not about disseminating code, the question was about communicating and finding it later. –  Doc Brown Apr 30 '13 at 19:05
    
@DocBrown Again, wikis are great for communicating, and that's probably why tools like GitHub have one built in. But the thing that makes code easy to find is not that it's mentioned in a wiki, it's that it's kept in a known place. That could be a wiki, but if we're talking about code that people are actually going to use (vs. a bunch of snippets that illustrate a solution) it should be a library of some sort, something that's buildable, testable, and which can be incorporated without multiplying the number of places where it will sooner or later need to be updated. –  Caleb Apr 30 '13 at 19:18

Well, it all comes down to communication.

Wiki's are great and you should definitely install and use one. A good internal programmers intranet is good if people read it and update it, so you're actually talking about a people problem there. You could suggest weekly "team update" meetings where everyone gets together and gives an overview of what work is going on. The tech leads (at least!) should be getting together and chatting about what each team is doing. "Brown Bag" informal sessions are great, schedule them at lunchtime and get people talking.

You also need a way of sharing code, packaging it, versioning it and distributing it. Things would be easier if you have a really well managed source code repository, arranged well into "common" and project folders.

If nothing like this is being done, bring it up with your boss, explain how it will benefit the company and suggest a way forward :)

share|improve this answer
1  
I would move the "common" concept up a little further in your answer. –  JeffO Apr 30 '13 at 18:06

Being in a company with 700 employees, within teams varying between 2 and 20 people, here is my experience.

On the team level

We have "standup meetings" everyday for around 15-20 minutes. We can quickly share common knowledge like "I did this function yesterday, it rocks so hard".

We also have a wiki per project. Which means we can share (technical) information about what's done in the project, including custom classes/functions that were built-in.

On the agency level

On the agency level, we have 4 tools:

  • Another wiki. It's mainly there to give us information about hardware and stuff, but we sometimes use it to share technical information to be reviewed before putting it on the company level.
  • Weekly meetings. They're mostly to know the progress of each team/project, but since we're mostly tech enthusiasts, we can bring up cool stuff.
  • Mailing list. We have a mailing with everyone in the agency. Lots of cool stuff/fun stuff/useful stuff gets through there.
  • VCS repository. Each agency has its personal repository where we have small projects, mostly modules that we use in different projects.

On the company level

On the company level, it's more organized.

The "agency level" wiki is actually part of the company's wiki.

And the wiki is then split up based on technologies. Thus, anyone can improve it, search through it, and basically give a life to the wiki.

There are also available mailing lists to which we can subscribe. Anyone in the agency can subscribe, and most people follow at least one or two technologies, actually most people follow 5-10 of them.

And the VCS is of course the best code sharing system.

Conclusion

To sum up, there's no clear cut solution. Knowledge sharing has always been a big issue, and will probably remain. There are lot of solutions to create knowledge bases, and one could probably fit your bill. However, some people are trying to get even better KB since current solutions aren't always very smart.

share|improve this answer
    
I feel that the conclusion should say nothing more than "wiki, wiki, wiki, wiki, wiki" but on a serious note, good answer, an internal wiki can be good for detailing higher level details or use-age, not to mention just being searchable is a good time saver. –  RhysW May 1 '13 at 8:34

Code review sessions can help. If your team meets regularly to discuss what was developed, then the person who came up with a solution can show the others how to use it. If someone brings up a point they're sticking on, other team members could propose an approach that increases reuse of existing components.

share|improve this answer
1  
Then 4 years and 600 functions later when you want to remember that one function that was made some time? Part of the OP's problem was trying to remember all of the things that had been created, while this is good initially it wont hold up over a period of perhaps, a month or two –  RhysW May 1 '13 at 8:35

The best way to handle something like that is to have a repository structure that has some simple conventions so that I know, as a programmer, if there is a function doXYZ, roughly where I should look for that function. Whether you're using namespaces, directories, modules, plugins, packages, whatever, your code should be modular so that functions that do the same thing or access the same data sources are in mostly the same spot.

share|improve this answer

Ideally, there should be at least one other person besides the author doing a code review on each checkin. The code review process can help mitigate the problem of many duplicate methods being checked in. Of course, you're constrained by the knowledge of the reviewers.

TL;DR: Code reviews for every checkin.

share|improve this answer
2  
Don't get it. Are you going to throw away tested and working code just because it looks like a duplicate in a code review? The question was how to avoid writing the duplicate code in the first place. A session like @daenyth's answer seems better. –  adrianm Apr 30 '13 at 22:07
    
If a reviewer told me I'm adding code that duplicates functionality, and I looked and found that they're right, heck yeah I'd scrap the dupe code. (I'd probably also check if my implementation is better, and if so, see if I could refactor the other implementation instead of adding a new one.) –  Carolyn May 1 '13 at 23:45

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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