43

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?

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
changokun
  • 491
  • 4
  • 9
  • 5
    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! – Rocklan Apr 30 '13 at 14:58
  • @DanPichelman You're correct. My comment came from thinking about his question applied to my own personal experience right now, which of course, is not everyone else's experience all the time. – Asaf Apr 30 '13 at 14:59
  • 4
    [Conway's Law](http://en.wikipedia.org/wiki/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
  • just have one file that everyone puts helper functions in... – nathan hayfield Apr 30 '13 at 18:17
  • 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
  • possible duplicate of [Best practices for sharing tiny snippets of code across projects](http://programmers.stackexchange.com/questions/193415/best-practices-for-sharing-tiny-snippets-of-code-across-projects) and of [How to promote code reuse and documentation?](http://programmers.stackexchange.com/questions/175066/how-to-promote-code-reuse-and-documentation) and [How can I promote software reuse in a large company?](http://programmers.stackexchange.com/questions/23652) See also: [Rule of thumb for cost vs. savings for code re-use](http://programmers.stackexchange.com/q/127118) – gnat Apr 30 '13 at 21:39
  • If you're a .NET shop, get a local Nuget server for your in-house libraries. – Andrew Lewis May 07 '13 at 18:00
  • I've always thought about an auto gen'ed newsfeed app that sits in VS, sees what you're all writing and spreads the word. * New class CreditTrade was created by Dave Smith. * New function SystemWebExtensions.CreateErrorResponse create by Leanne Um, Rhymes. – Luke Puplett Aug 21 '13 at 10:41

7 Answers7

28

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.

Caleb
  • 38,959
  • 8
  • 94
  • 152
  • 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](http://en.wikipedia.org/wiki/Big_ball_of_mud). – zzzzBov Apr 30 '13 at 16:59
  • +1 - finding and reusing code from one project to the next "is" the problem. – JeffO Apr 30 '13 at 18:05
  • A separate repo might be overkill for much of the stuff, but if your build system supports some kind of modularity (most do), then at least pulling it all out into some sort of util module would be enough. – TC1 Apr 30 '13 at 18:09
  • 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
  • .. create a customized library for their own product, with a completely different life cycle. On a cross-team scale, the DRY principle is much overrated. For example, there are zillions of free open source classes/functions floating around in the web, and lots of people put those code into libraries without getting that huge freakin' mess you mentioned. That is exactly the situation I have in mind - those open source authors would rarely provide the maintenance requirements of all their code re-users. – Doc Brown Apr 30 '13 at 19:18
  • On the other hand, there are also some open source libs and frameworks for which the original author does maintenance new releases, and which can be re-used without any tweaking. But those libs have a completely different quality standard. – Doc Brown Apr 30 '13 at 19:22
  • @DocBrown Yes, contractual obligations, licensing issues, and configuration management all need to be taken into account. You'll notice that I already pointed out that it can be a good idea to maintain different libraries with different maintenance requirements. Presumably, since the OP is talking about disseminating classes/functions within a team, the maintenance requirements among the various authors/projects are relatively uniform. – Caleb Apr 30 '13 at 19:29
  • @DocBrown *Your answer sounds reasonable at a first glance* Are you saying that my answer **sounds** reasonable but really isn't? IME, if code is good enough to reuse it's good enough to maintain and manage properly. There's not much benefit to posting crappy solutions somewhere so that others can copy and paste them. If you're going to share half-baked code, you should *at least* manage the code so that you can fix all the code that uses those solutions later. – Caleb Apr 30 '13 at 19:42
  • 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
  • I'm not sure if this answer really helps on a small scale. We're having the same issues in our team. For instance we've started doing a lot of manual date formatting, so I've moved all the code into a class called `DateFormatter`. The next time someone wants to format a date instead of writing out yet another formatting function it would be better to put it through that class. Putting this one class into an external library seems like overkill, so letting my colleagues know (and making sure they remember to use it) is still an issue. – Thomas Clayson May 01 '13 at 08:20
  • @ThomasClayson If you're all working on the same project, then sure, there's no need to pull things out into a separate library. In this case, your project *is* the equivalent of a library of useful tools. I'd expect that you already have some means of communicating with your team about what's in the project -- documentation, team meetings, etc. As I read it, the OP's question has more to do with keeping track of that date formatting code as you move onto other projects in the months ahead. – Caleb May 01 '13 at 08:32
13

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.

Doc Brown
  • 199,015
  • 33
  • 367
  • 565
  • 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
  • @Caleb: I agree that writing high quality library code is something people should try to achieve. But I try to stick to the original question (in the way I think it was meant). – Doc Brown Apr 30 '13 at 19:26
  • @DocBrown Perhaps a point on which we can agree is that the way to communicate/disseminate functions/classes that might be useful to others within your team or organization is to put them in a common, well-known location. – Caleb Apr 30 '13 at 19:33
7

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.

Florian Margaine
  • 6,791
  • 3
  • 33
  • 46
  • 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. –  May 01 '13 at 08:34
6

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 :)

Rocklan
  • 4,314
  • 1
  • 15
  • 29
4

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.

Daenyth
  • 8,077
  • 3
  • 31
  • 46
  • 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 –  May 01 '13 at 08:35
2

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.

Jonathan Rich
  • 2,958
  • 16
  • 14
0

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.

Carolyn
  • 139
  • 2
  • 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 01 '13 at 23:45