How do you go from idea to implementation when designing classes for other developers in other locations?

Question

I'm looking for inspiration on how to design classes from scratch in a project with multiple developers in different locations (so no whiteboard sessions.)

Let's say you're tasked with implementing a rather big feature that is going to be used by the other developers later in the project. This feature will require several classes and will interact with other classes already in the project. Of course you want the other developers' input before you go on and implement the whole thing. Now, how do you proceed?

I would start with the best tool available: pen and paper. But then what? I would like to materialize my lines and bubbles and notations on my paper to the screens of the other developers. Is the best method to simply scan and e-mail the paper? Are there good patterns for writing down a design as text? Are there any online tools that can quickly model a class design? Should I simply write the "skeletons" for the classes and ask for feedback?

An important point to think about here is that the only communication available is phone and e-mail, due to developers being located far away from each other.

Answer 1

Use video conference : talk to each other using you laptop's micro, and let them come into your computer, using VNC, so that they can see your screen.

From that, use whatever modelling/text editor as a support : Paint, Word, WinDesign, Objecteering, etc. Best way to communicate.

PS : I agree that pen & paper is the best, but when it's for you, not for foreign developpers. So forget scanning and emailing ^^

Answer 2

I don't have experience with this lack of co-location situation, but I agree with the idea that the pen and paper approach is the best to start discussing a design. Scott Ambler talks about the use of POWs (plain old whiteboards)... is the same idea. The first modeling approachs could be captured just taking a picture with a digital camera, don't waste time with a fancy UML layout using a tool until the model is more solid. Taking pictures of the whiteboard saves a lot of time.

I guess the use of video conference as proposed by Clement Herreman is good enough to discuss the model if you can share a portion of your screen, so everyone who is conferencing can see the pictures of the model under analysis.

Answer 3

First, I start to read the requirements and documentations and try to get a rough sketch. This is mostly done inside my head and partly on paper. (I have a very good memory.) The first phase of the design is often done away from my computer! Ideas might pop up in my head while I'm in the car. Sometimes, I'm even getting new ideas while dumping something smelly in a large, porcelain pot in a very small, locked room. In general, the design ideas tend to pup up when it's quiet and I have a chance to let my mind wander around a bit.

Almost two years ago, I did have a big project that needed to be designed. Another developer had been working on this already but became utterly frustrated by it, to just leave the company simply because after several weeks he still hadn't found a good solution. So, then it was my turn...

I had the advantage that I could work at home, so I did. I've spent the first day of designing in my bedroom, in bed with pen, paper and documents. I had the notes from my former colleague and could see that he made things far too complex so I started to divide the problem in smaller steps. I continued wasting paper making notes, doing calculations in my head and comparing my notes with the documentation and other notes. That first day, I never used my computer.

The second day, I started to type a technical design and write some code to test a few principles. I still spent a lot of time away from my computer, though, taking short naps in-between to take some breaks from the heavy thinking. It took the whole day but in the end, I had the whole concept finished on paper.

The third day, I had my concept printed and shared it with my teammates. While I continued to set up the basic requirements for the code, they could start judging my design and point out the flaws. That day, they didn't find any, although I did leave a few in it.

The next day, a teammate and me started to implement the Proof-Of-Concept code that would be needed to get it all to work. Within two more weeks, the whole beta-version was finished and just needed some tune-ups. This was something the rest of the team would do, while I went on a holiday.

After returning from my holiday, the whole project turned out to be a great success and the functionality was very well-received by our customers!

So, required materials: small rooms, pen, paper, a bed, lots of coffee, food and relaxation. Stay away from the computer and be lazy. (By lazy, I mean: avoid writing code immediately. Just think, which will make people think you're just doing nothing...)

When designing something for others to implement, you will need out the first part of the design yourself, as complete as possible. Just stick to the big things, allowing room for little things to be added by your team. And most important: rely on your team to take over your job at a certain point and be prepared to step back once they start moving!

Answer 4

Use UML, CRC cards, and as others write - video calls. Also such services like digitalsamba will allow you to share your desktop and any documents among any number of participants.

Answer 5

Don't go on it in a Big all or nothing session where you are trying to design all the classes of the system.

Take 1 or 2 features and start from there. Don't have single big meetings, instead do quick small meetings where you evaluate those features. You will be able to apply lessons learned to the next ones. It will also allow you to go deep in details if needed.

If this will integrate with existing code, ask to the corresponding developers how it affects it.

If we are talking different subsystems, keep integration points at a minimum and keep them simple. Sometimes you just can't/shouldn't fit preferences of many other teams into it, but instead have the other team do a simple class that exposes your api in the way that's most convenience for their code. You don't want to get complexity all over, keeping things simple is usually the best path.

Also note that all this investment in defining integration points through these design meetings is mainly if we are talking about subsystems integration. Big projects with teams working on different parts of it. You don't want to get into any internals of the parts they each develop (unless you are talking architectural concerns ... but you should have someone able to take care of that in those teams ...), instead you want to focus on how you will integrate.

It is different when you have distributed team members working on the same part of the system, there as long as you have clean code (and that's the only feedback you should focus on) you will be able to go on with the team and evolve the code into what's really needed to be implemented. With these team members you should have constant communication, if time zone differences get in the way you should have at least 30-60 mins of overlap ... you can do without and I have done, but the overlap really pays off.

Ps. I have been working extensively with distributed teams for 4 years now with both cases I mentioned above (different teams on subsystems of a big project, same team working on a specific subsystem), and 2 of those years as been with globally distributed teams.

Answer 6

I actually don't agree that "the only communication available is phone and e-mail". The web has changed a lot, and there are lots of great new ways to do sharing, and most of them are free.

Edit: links in list form

• Microsoft SharedView
• Adobe ConnectNow
• Skype
• Drop.io
• Google Docs
• Office Live
• Skrbl
• Google Code Reviews
• Gliffy

Answer 7

The first thing is to write out the code that will use your interface. How do you want that code to work and look. Then start to write your code for that interface.

Have the interface help you rather than having you fight with the interface.

Answer 8

You can try using a collaborative mind mapping tool, like http://mind42.com/ It is not intended exactly for modeling class or activity diagrams for instance, but it might help collaborating when exchanging ideas is critical.

In addition you can use a source control system, where you can store not only source code prototypes and skeletons, but also the model files (from Rational Rose for example or your favorite modeling tool).

I used before to store also word documents in the source control, which contained extractions of the class diagrams, but it was not so useful.

Answer 9

• Make sure you have clearly-defined, documented requirements.
• Everyone should review the requirements to get an overview. One person can be in charge of the initial design. The design document can be as simple as a detailed listing of how the requirements will be implemented in your system, or as complex as a fleshed-out UML diagram, depending on the needs of your project.
• Use a conference call to meet and go over the design.
• Use an instant messenger program to send links, hash out details, and (later on) for collaborative troubleshooting as needed.
• Some projects (particularly open source) often have an IRC channel where developers and users can hang out, help each other out, and go over things.

Answer 10

Consider using IdeaTorrent

Answer 11

SVN or CVS is a must have, so you should always get access to your co-workers parts and can see the existing interfaces and the description. Also all people in the team should use document markers in there prototypes for a automatic documentation system like Doxygen. So its easy to generate the documentation for all other developers on the fly. This documentation should be available in the repository (mostly in a "doc" folder) so you can every day make an update with your working copy and also get the updated documentation.

Software design is also the part of creating a big picture before one line of code was written. So there should be a mindmap, UML diagram, flowchart etc. about the whole project or the part of the project. So its easier to understand also for other developers coming new to the project.

Because you have the interface descriptions with the generated documentation, its not a problem to build your prototypes. Because of the mindmap, UML, flowchart etc. you get a idea of the whole thing. The documentation markers should also including something like "@author" so you can easy contact them if you need a deeper description if something is not clear. Often its a good idea if the people are using an instant messenger (MSN, ICQ,...) so you can easy contact them. Often its only a short question so there are no needs to call someone or write a mail (where you eventually get the answer the next day)

The rapid prototyping is another thing in the game. There is the question if the classes are for a GUI or if this are "only" the program logic. For the GUI there are many tools for the frameworks available which can generate the classes, so you only need to implement the inner logic (event handling) and the interfaces to your co-workers classes. For the other parts I suggest a UML tool (mostly you only need the class diagram). There are free tools available like ArgoUML running also on Linux. This tools can generate a big part of the class design also for different languages (C++, Java)

Answer 12

Keep it simple with a blog.

Each developer can post their ideas and progress, commenting to each other along the way. I've used this in the past and it was engaging.

If there is a client, manager or other interested party they can see that people are active and working on things.

Answer 13

You could do worse than develop a shared vocabulary, not only for discussing the problem domain but also the solution domain. In the solution domain, rather than talk about the specific classes - describe your potential solutions in terms of design patterns.

I'm sure they're already familiar to you, but in case they aren't - a pattern allows you to describe whole subsections of a solution in terms of the reusable designs it will use.