Documentation – How to Keep Track of Classes and Functions Written by Your Team

code-reusedocumentationteamteamwork

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?

Best Answer

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.

Related Topic