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?
10
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.
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.
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.
1
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 🙂
1
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.
1
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.
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.
2