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.

This question already has an answer here:

I started working at my current job about 8 months ago, and its been one of the best experiences I've had as a young programmer. It's a small company, and both my co-developers are brilliant guys.

One of the practices that they both have been encouraging is lots of code-reuse. Our code base is mainly C#, and we're using a centralized revision control system.

The way the repository is currently structured, there is a single folder in which all shared class libraries are placed (along with unit tests for each library), and our revision control system allows for sharing or linking those libraries out to other projects.

What I'm trying to understand at this point is how the current structure of the folder can be made more conducive for finding those libraries again. I've talked to the other developers about this, and they agree that it's gotten a little messy. I find that I am sometimes "reinventing the wheel" because I didn't realize that there was an existing piece of code that solved a particular problem.

The issue is complicated further by the fact that we're sharing some code between ASP.NET MVC2, WinForms, and Windows CE projects, and sharing code between applications built against multiple versions of .NET.

How do other people approach this? Is the answer in naming the libraries in a certain way or is it preferable to invest in some code-search software? Is the answer in doc comments? Should we be sharing libraries at all or should we simply branch the class libraries for re-use?

Thanks for any and all help!

share|improve this question
add comment

marked as duplicate by gnat, MichaelT, Corbin March, Kilian Foth, ChrisF Sep 9 '13 at 20:28

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

7 Answers

up vote 11 down vote accepted

I think the answer is at least in part in communication. If all developers communicate well about what they're working on, others can suggest which methods may be already implemented and immediately reusable. Similarly, if you develop something that fits in well in the common libraries, let others know that it's there.

Leaving it up to a search tool has always been insufficient, since in order to find something, you have to first know to look for it and what to look for. If you know what you're looking for, all you need is grep.

In .NET doc comments might help you along a bit, since Intellisense can help others find existing methods, but again -- they first have to look in the right class/namespace.


Edited to answer @awmckinley's question in comments: In an ideal situation, when older developers leave, there are still some left. With sufficient communication, those who are left can continue spreading the knowledge among the new developers (and then the cycle repeats). In absence of that, I like keeping a wiki going with some information on available functions. Organizing it can be tricky. I try to group things by purpose rather than namespace, since that (theoretically) makes it easier to look things up, but I haven't had much opportunity to test if that's really true.

share|improve this answer
    
I definitely agree about the need for communication (esp. letting the other developers know what you're working on). Are there any ways to one capture that information in such a way that it can be helpful to new developers after older developers leave or have split off into separate teams? –  awmckinley Jan 7 '11 at 1:02
    
+1 for communication. And I think one way to improve it on a small company is the well-known 15-minute daily stand-up meeting. Helped my team a lot over last year. –  Machado Jan 7 '11 at 11:29
    
@awmckinley I edited my post to answer that. Hope it helps. –  Anna Lear Jan 7 '11 at 14:15
    
Yeah, definitely. I'll have to talk to the guys about the Wiki idea. Maybe dividing a Wiki into a Silverlight section, an ASP.NET MVC section, etc would be helpful. –  awmckinley Jan 7 '11 at 18:44
add comment

how the current structure of the folder can be made more conducive for finding those libraries again.

There are limits. Years ago (decades really) I read a nice paper by some folks at the old AT&T (before they were broken up and reassembled) that described profound limitations in understanding a base of software and "effectively" reusing it.

The issue is this.

  1. People can't find stuff. They just can't. The number of StackOverflow questions that are trivially answered by the first hit in a Google search indicates that some number of programmers can never find stuff even with Google.

  2. People can't understand what they find. The more there is, they less the can understand of what's "out there".

  3. NIH. Not Invented Here. Some people cannot reuse because their DNA prevents them from simply reusing. There are always "issues" or "concerns" and they find great excuses to reinvent instead of reuse.

None of this is related to folder structure.

Fine-tuning the folder structure is an attractive nuisance.

You have to actively proselytize, explain, enhance, document, share, coerce, and create a cooperative environment.

  1. You have to find stuff for people. In order to determine who can't find stuff, you have to meet with everyone periodically to understand their needs, their projects and their problems. Don't waste time reorganizing the folders. Go out and meet your "customers".

  2. You have to explain, clarify and document everything over and over again. And then revise it again when people use it incorrectly, can't find it or misunderstand it. Don't waste time reorganizing the folders. Meet your "customers" and provide them information they need to understand what they find.

  3. NIH cannot be overcome. There will always be people who simply refuse to cooperate. There they are. Work around them or cope with them in some way. All the clever folder organizations in the world won't stop them from forking a project because they have to do it their own way.

share|improve this answer
1  
+1: In regards to #2 (You have to explain..."), Sun Tzu says: "If words of command are not clear and distinct, if orders are not thoroughly understood, the general is to blame. But if his orders are clear, and the soldiers nevertheless disobey, then it is the fault of their officers." –  IAbstract Jan 7 '11 at 17:44
add comment

One way is to store those libraries not in a VCS (Version Control System), but in a repository manager like, for instance, Nexus.

That way:

You will store reference to certain libraries through their GAV(Group-Artifact-Version)+classifier+SHA1 in a simple text file you can version along your other data in your RCS.

share|improve this answer
    
Wow! That looks very interesting! We'll have to look into that... thanks! –  awmckinley Jan 7 '11 at 1:05
add comment

Frankly, I have found that as with the web having information in nicely laid out directories is not enough, you need to have a extensive code search which can be used to find snippets and sometimes blocks of code which can be reused even if it is part of the "shared code" project.

share|improve this answer
add comment

I am not sure that there is good answer to this. I have run into this exact scenario with a senior developer that was new to our team. He had essential done something that was already part of a library. He was just unaware that the library existed. I think that this is a case where code reviews can be extremely productive. New developers to a team simply just don't know the code base enough to realize that there might something that already exists that solves a particular problem.

At first I wanted to suggest documentation possible in the form of wiki, but I don't think that is helpful. You can have someone look it over, but chances are that they might not even understand what the intent of the library is until they run into a situation where it is applicable. I think documenting libraries can be great for reference purposes, but if you don't even know what to look for then the documentation is largely useless.

share|improve this answer
add comment

One problem is that there are usually so many small entities you have to search through, forcing you to do so many clicks, getting lost in details deep in there and then don't find your way back.

It may be an approach to scan the source code with a little script (nothing sophisticated, some simple keyword scan/pattern matching is enough) and assemble it into one big list, like a book's table of contents:

File name (full path within library folder)
    Class name
        Public method name
        Public method name
        ...
File name
    Class name

When you're facing a specific problem, scan through the list. If you find anything where the naming could fit your specific problem, you can explore further, with the complete list in a separate window so you can quickly back out.

The longer you do this, the better you will learn what's in the libraries, how good and consistent your choice of names is, and maybe finally introduce one single specific comment line that describes in a few keywords what the library is for, and that is included in the list.

Don't include too much detail within this list, it makes it harder to quickly glance through it.

share|improve this answer
add comment

We use a Wiki that all developers have access to that points out our standards, quick reference items, and pointers to shared "widgets" that we have in our framework. We also send out an email to the group if there is a significant new piece of shared logic that everyone should be aware of. These also come up frequently in our code review discussions and the periodic developers' meetings.

share|improve this answer
add comment

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