How to find already existing code | How to arrange code in a way it can be found again [closed]

Question

I'm refactoring the framework of our company, trying to fix the issues we had in the past.

We're a team of 6 developers, and we have various needs and issues in regards to tidying up our framework.

Right now, we want it to be the solution we import in all our projects, because it has all the code we reuse every time. The solution would contain several projects, one for each feature. For example, we dont want to have our social network classes in all our projects, so that's in a separate project. But all our string extensions or authentication classes can be in the main project, since it's pretty much needed every time.

So in the end this solution will contain a lot of code, a lot of projects, and a lot of namespaces. Which is good, tidy, organized, but stuff becomes hard to find.

My question is, as a developer, how do I know if the code I need already exists in that framework ? Lets say I need to resize an image, for the sake of the example. I'll maybe search the code for Image and find about a thousand results. I'll search for the word size and face the same problem, so I'll try resize or resizing and see that the code does not exist in the few results I've got. Right? No.

In the end, it already existed, but was called changeSize(), and now I've written the same code twice, under two different names. I've placed it in a namespace/folder called extensions and lets say the other one was in graphics.

Now the problem is, I didnt know it existed, I tried to find it and couldn't find it. And where I looked manually it wasn't there, so in all good faith I made a mistake. How can this be avoided? Everyone should know the complete framework ? We could ask around ? We could write a complete documentation ? That seems somewhat unreasonable, because lets face it, we won't have the time or motivation/dedication to just read code for the sake of knowing it exists, asking every time I need something is quickly gonna get out of hand and annoying, and the documentation has to be both maintained and checked, which comes back to the first problem : not enough time, not enough discipline.

This is pretty bad, but I must admit that is the reality of what we're in. We've come up with a some solutions, but its not enough :

• Every time you want to add code to the framework, it has to be through pull requests, which everyone has to read and approve. You don't have to review, just browse so you might remember it. That way learning the framework will come slowly, but it will eventually. That only helps for future changes, but it's something.

• We add a series of tags for each class which we consider valuable keywords, like on stackexchange, to help people find the classes they need. Those tags will be extracted because they're documented, and so you should be (haven't tested yet) able to find classes by tags in the docs, or just use Find solution-wide and see the results on the various tags you could type. Exemple in the following image

This is not perfect, it has flaws, but that's where we're at.

Finally, my question : how do we improve on this? How do you guys do it? We keep writing the same code twice or even forgetting stuff exists. And even if we know it exists, we sometimes struggle to find what we wrote ourselves just because there are so many classes and different names one thing could be called.

Answer 1

One important point is to have a consistent namespace structure and to use descriptive names. Connect can be vague, but ConnectToNetwork or ConnectToDatabase is more clear. Use terms that are standard in the industry - "ResizeImage" instead of "ChangeSize", for instance. Follow the structure of your language's standard libraries as much as you can - Andy Hames' answer is a great example of this.

I would separate out as much as you can into different projects and deploy each of them separately. Image extensions don't have much in common with authentication, so there's no reason to bundle everything together. This cuts down on noise when using Intellisense, etc. Be wary of separating out too much though.

As a final point, consider who is going to be using your framework and how. Documentation is pretty vital here, as the framework is quite big. Developers who are using it may not be the same developers who wrote it, and having a little blurb pop up in Intellisense to clarify what the method does is crucial - can you imagine not having MSDN documentation? While you don't need to go to quite the same length, requiring each public method or property to have proper (and current!) documentation will go a long way to your framework being used more correctly. And, a small document describing the overarching structure of the framework may not be a bad idea either - something that points out what the various projects / high-level namespaces are and what they do / should contain.

While documentation is a pain, your framework should not be changing much (it is a framework, after all), so the documentation should be mostly write-once and done. Being able to use your framework to its full extent is a nice benefit from proper documentation as well, and will prevent rewriting code or fruitless searches.

As mentioned in the comments some third-party platforms, like StackOverflow Teams, can be quite beneficial here. After all, even with MSDN and proper documentation on members, finding a class or method you don't know even exists is tough without knowledge from somebody who does know. Documentation doesn't always need be XMLdoc or class diagrams.

If you find that you're needing to update large parts of your documentation often, I would take a step back and look at why that's happening. Frameworks should be largely static, so if you're making a lot of sweeping changes to a particular area, perhaps that class or set of classes doesn't belong in the framework just yet.

Answer 2

The way I typically organise these sorts of utility methods is to replicate the namespace structure of the type the method applies to.

In your example, for extension methods for the System.IO.Stream type I would use MyCore.IO.StreamExtensions. Extensions for the System.Net.Mail.MailMessage type? MyCore.Net.Mail.MailMessageExtensions, and so on.

Likewise for types derived from existing types - my custom MailAddress class would be at MyCore.Net.Mail.MyMailAddress.