I like to involve my Staff Members when designing new code for the MUD. As such I've tried finding good ways to handle this. In this post I'll roughly describe how this is done, and finally I'm hoping others will share their experiences on the matter.

First of all, I'm the kind of guy who likes to make a very detailed design before even coding a single line. As I'm the only coder on our project at this time, I have the luxury of making sure this is (almost) always so. We have a section of our forum dedicated to discussing design matters where only Staff Members have access. Whenever I or someone else comes up with an idea, we start brainstorming by throwing in lots of ideas on the matter. My role at this stage is to moderate the thread, keeping the discussion on topic, and throwing in my own two cents.

As the idea matures we start narrowing it down, and go into more detail. Generally I try getting people to present ideas from the perspective of the user (player), often by presenting a sample mud session.

When it gets detailed enough, I start sorting things out and make a UML model on the design. This often reveals things that we discuss further.

At some point the model is detailed enough that the implementation emerges almost by itself. At that point I code it, and the result usually does exactly what we intended, because we have already dealt with most potential problems.

I've also looked at many open source project management systems, but I haven't found any that does what we need. So using a forum, along with keeping the discussions on topic is how we do it.

So I was wondering if anyone else have found good ways to deal with collaborative design-processes? While the above approach works, I can't help feeling that there must be more efficient ways of doing it.

Any thoughts? Experiences? Ideas?

Edit: The reason I'm posting here instead of the Design forum is that I'm mainly interested in discussing the way we organize people, and working efficiently as a team.

My style is exactly opposite yours, but if I were going to try to do things that way, one thing I would try out is the ticket system, Flyspray, that we use at ye olde day job. I've liked it a lot more than I thought I would. Whether it'd work better for your purposes than your forum software does, I couldn't tell you.

That's certainly my tactic. If you ask me how something I'm writing is going to work, my answer is "I'll tell you after it's finished". At the time I start writing code, I generally haven't the faintest idea how something will work.

Most of the processing in my brain happens below the threshold of consciousness, and I find the only way to get my subconscious to apply itself to the problem is to start coding it. After bashing out half a dozen methods, I certainly find myself thinking "oh, hang on, that won't work because..." - that's a kind of thought I never have in design discussions. I feel my way through the problem with the code changing under my hands until it gets to the point where it works correctly.

I also find that the best way to achieve "good" code is to start with "working" code and then refactor it. Once you have it up and running it's easy to say "ah, yes, this bit is actually much the same as that bit, so we should abstract it up to a common superclass". You'll never get your class hierarchy 100% correct at the design stage.

In my real life job, I've found clear requirements and a solid design invaluable - they are practically essential for ensuring that the developers actually produce the end result that the customer has asked for, and do so within the budget and timeframe originally specified.

When working on my mud, things are a bit different. I'm both the customer and the developer, so as long as the requirements are clear in my mind I often don't bother writing them down. Perhaps just as importantly, there are no development costs or time restrictions; the mud is a living and constantly evolving beast rather than something with a desired "end result".

Before I started developing my mud, I did spend several months putting together an overall design of the core game, constantly refining it through discussion with the other admin. I also created a separate mud as a prototype to test my combat system ideas. Since then I've used my mud's forums to brainstorm many concepts I wasn't sure about, which players and other staff members have discussed and responded to with feedback, helping me shape the idea into something I felt was ready to start developing - and I've also found MudLab a good way to get an outside perspective on certain design ideas. But overall, I've found that many of the software engineering practices I follow in my real life job don't apply very to working on my mud.

When it gets detailed enough, I start sorting things out and make a UML model on the design. This often reveals things that we discuss further.

Since you bring it up I'm also positively allergic to UML. I can't stand it. The only time I ever put a UML diagram together is if I need to explain something to some of the less articulate junior devs. And even then I grumble about it.

They're fine if that's the way your brain works, but mine doesn't work like that; my visual/spatial skills are reasonable, but my verbal skills are off-the-scale high (according to some tests I took 22 years ago, anyway, and who am I to argue? ) so I'm much more comfortable thinking verbally rather than visually. If I'm presented with a UML diagram, it doesn't reveal or clarify anything, I just have to spend extra time translating the diagram into English before I can make sense of it.

If UML works for you, great; just understand that not everyone's brain works the same way that yours does, and it's perfectly possible for someone to have off-the-scale abstract reasoning skills (according to the same test 22 years ago! ) while not being comfortable with UML; you shouldn't assume that it's an appropriate way to communicate with every member of your team, let alone that it is essential to good software design.

If UML works for you, great; just understand that not everyone's brain works the same way that yours does, and it's perfectly possible for someone to have off-the-scale abstract reasoning skills (according to the same test 22 years ago! ) while not being comfortable with UML; you shouldn't assume that it's an appropriate way to communicate with every member of your team, let alone that it is essential to good software design.

UML is certainly no magic cookie, I agree to that. However, I don't think it has anything to do with "off-the-scale abstract reasoning skills" or not. UML is just a way to organize things, AND to use as a quick reference for later. A few months from now I can look at my own code and scratch my head. In those cases I can look at the UML which will then trigger my memory very efficiently.

And I don't use the UML to communicate with my team. I don't think many of them would find it very useful. Just having everything in your head is fine when you work on just that one thing, without interruptions, until you're done. But what if you have to abandon your current work for a couple of weeks or more? Do you really have so perfect memory that you can just continue where you let off without spending time getting into the same mind set? I know I don't, and in these situations a mind-map of sorts in invaluable, because that's more or less what I use it as.

Just having everything in your head is fine when you work on just that one thing, without interruptions, until you're done. But what if you have to abandon your current work for a couple of weeks or more? Do you really have so perfect memory that you can just continue where you let off without spending time getting into the same mind set? I know I don't, and in these situations a mind-map of sorts in invaluable, because that's more or less what I use it as.

That's certainly crucial. Thinking about it, what I believe serves that purpose for me is a lot of evolved design and coding practices and patterns that make it so that any particular thing I might be looking at implies a large number of things about its context.

I suspect that, to outside observers, the process of evolution looks like me doing a lot of refactoring of things that were working just fine, and application of these practices and patterns looks like a lot of inexplicable nitpickiness.

But what if you have to abandon your current work for a couple of weeks or more? Do you really have so perfect memory that you can just continue where you let off without spending time getting into the same mind set? I know I don't, and in these situations a mind-map of sorts in invaluable, because that's more or less what I use it as.

Well, as I said before, I typically don't have a plan worked out in advance, I make it up as I go along. It's conceivable that if I drop something for a few weeks and come back to it I'll start moving in a different direction from the one I was originally taking, but, if so, the second one is usually an improvement on the old one.

In terms of keeping track of what the code does, I write my code in such a way that it is obvious what it does. One of my most important rules is "never put comments in your code". Many programmers are a little startled by that idea; but, to my mind, if any piece of code you write is sufficiently obscure or complicated that a stranger who looks at it needs a comment to understand what it does, that means the code needs refactoring. Properly written code doesn't require comments. The code itself tells you what it is doing.

There are any number of secondary rules that follow on from that; things like "it is rarely a good idea to have a method (function) that is more than half a dozen lines long" or "it is almost never a good idea to pass more than two parameters into a method". If you find yourself doing either then, again, you need to refactor.

Granted, it helps that I programme in Smalltalk. Rules such as the above are much harder to follow in low-level languages like C.

In terms of keeping track of what the code does, I write my code in such a way that it is obvious what it does. One of my most important rules is "never put comments in your code". Many programmers are a little startled by that idea; but, to my mind, if any piece of code you write is sufficiently obscure or complicated that a stranger who looks at it needs a comment to understand what it does, that means the code needs refactoring. Properly written code doesn't require comments. The code itself tells you what it is doing.

I noticed that when writing in our scripting language I never bother to comment even the largest of functions (15+ pages), mostly due to it being written in such a way that its purpose is obvious.

However, having dealt with a convuluted codebase lacking in comments I can tell you that I do very much appreciate them. Comments are the most important (and most forgot for us) when someone is coding something that's perfectly trivial in the context of a coding session, but turns out to be a headache to track down the meaning later. One prominent example was tracking down what val1 and val2 meant and their average values for about 7 seperate functions.

Proper naming of variables and functions is essential to write near comment-less code as your variables themselves become the comments. However, when you add other programmers into the mix who have their own style of coding things get a little more hazy. People generally don't like it when you superimpose your own stylistic preferences upon them.

As far as refactoring goes, this post itself has been refactored a few times now to further elucidate ideas and cut out junk text and verbosity. I do the same thing with code as well, as I find that like any artform you really just have to let it flow through you. You shouldn't paint a picture by plotting out every brushstroke, and equally so you shouldn't program a work of art like a MUD by planning out every detail. Just let the damned thing evolve.

Well if you want to limit your resources by imposing strict code guidelines, you're more than welcome to. However, if later on down the road you start wondering why you're not getting decent help or wishing you had more staff you should keep such things in mind. I know I only put up with so much anal retentiveness on any project I work on, and I'd expect many others are the same.

I think more to the point: If you want help, sometimes you have to get used to the fact that some people do things differently than you. That, or just work alone. Expecting someone to change how they write just for you is just as ludicrous as expecting them to only talk in a Lord British manner around you. You're restricting the independence of those involved in the project, and though you may find it more efficient, you're potentially impacting morale.

I suppose it depends on your situation, personality, and personal style. I know one of our programmers hates the base we have right now pretty bad because of its overuse of macros (it's a circle base), so I can empathize with your issues. Wanting someone to write decently clean code isn't a bad ideal. The context I was replying to though was Shasarak's idea of (and my own experience with) creating code that needs no commentation.

My point is that if you can not stand people coding in a way that doesn't mirror your exact style is:

A) You're going to either have a hard search for finding quality programming help.

or

B) You're going to spend a lot of time programming on your own.

If either are undesirable goals and your guidelines are as strict as was being discussed above (commentless code), then you may want to reconsider.

Just incase I wasn't clear: Generally good coding practices are not included in the above assessment.