I've never worked with more than one person before and never commercialy. I've never been the lead on a project before either and the "Design Documents" I've seen written up by the only two people I've worked with didn't go into detail when it came to the exact ways two objects(classes) would interact code wise. Though I was the main programmer, you could almost say I was the only programmer, so technicalities such as the names of functions or the order of variables was mostly up to me.

I, and I'm sure everyone, have my own convention when it comes to ordering arguments of a function so there has never been situation where I wanted to use a function and didn't know what all the arguments were. Like I said the documents I worked off of weren't super detailed so there are alot of times were you have a function like so. void Map::FindPath(), but no indication of what variables are to be passed to the function, and would assume there are none.

I Was thinking though what if I were in a group were one person was coding the map and pathfinding logic, and I was coding the units that use the map to know were to move around. Should the design document have the exact parameters that will be passed to the function, or would that be up to the two persons to collaborate on the subject. Something like the map coder writes the class then tells me this is how you use the function?

Should the DD basically include a rough draft of the header files?

Or should all functions be designed to work without arguments, but really use an overloaded version that is the real function?

You just work around the other guys code then. If before hand you say what your interface to using the FindPath code is, then your fine. For instance FindPath() could be in the units code itself. Or you could say given point A,B, give me back point C. Doesn't really matter what the design is or even if you know it. Simply when hes done w/ his work to FindPath, he could let you know and say heres how you use it.

When I started an engine from scratch I just went here everything I want and what it needs. The connection/interface of classes/objects can always be changed or done multiple ways. You could have multiple find path functions based on different input that certain units might have. It is ok to have things evolve and interact as you move along.

As far as design on paper: My last engine I said heres everything I need, class Light,Mesh,Texture,Physics.......etc. Layed out all the member variables, and then started to code functions, I never really gave parameters to functions and such. You cant call a function that doesn't have code defined inside of it so you don't need to know the interface anyway. Just pass parameters needed when the "FindPath()" function is defined. If you dont have those parameters in your other class, then make them.

From my experience, the technical design document was written at the beginning of a project because a publisher asked for it, and then was promptly forgotten about. Programmers huddling together in front of a white board discussing data flow is how information is shared, not through a doc.

Zero code.

Code is written as needed, not specified in advance. Similarly, art placement and visual details should be iterated on and adjusted based on feedback, not specified in advance. Implementation details should not be specified because they are discovered and improved at implementation time. There will be several iterations on code and art that have nothing to do with the over-arching design.

The design document should specify the end results. Example statements might include: Context menu items appear, showing modes A, B, and C. The camera should be an overhead view that follows loosely behind the player. A large hud panel will show in the bottom of the screen in a strip below the main window. A map should appear on screen to help guide the player. An arrow should show up guiding the player to the next goal. Etc.

The design document should NOT specify the code implementation details. That is an implementation detail left to the programmers.
The design document should NOT specify the art and final placement details. That is an implementation detail left to the artists and designers.

Specifying interfaces in advance in some kind of design phase, giving them to two different teams that implement different parts of the code, and then putting things together is going to fail. What you should do is simply grow the code base from a minimal seed that does something useful.

In your example with map logic / pathfinding and units code, the best way to start is for somebody (or a pair / triple / tuple of programmers) to write an initial rough implementation that does one very simple thing, perhaps showing entirely flat terrain with one unit that can be moved around or moves around by itself without any fancy pathfinding. Then you identify additional features that can be implemented without too much cross-interference (for example: different terrain types; proper path-finding; user steering; attack and damage; buildings and other stationary objects in the map; additional UI elements; unit AI behavior), assign them to different people and use a (ideally distributed) version control system to let them work independently and simply merge the result of their work whenever they're ready. And of course, make sure that people talk to each other about issues they encounter.

Note that no code design document is involved in this. The code should document its own design, and if you must, you can extract class diagrams from it or JavaDoc-style documentation automatically.

A very important thing to keep in mind, however: Not having a code design document is not equivalent to not thinking about code design or rather software design. You definitely need a conscious process of reevaluating software design decisions regularly, when it makes sense. It is very difficult if not impossible to truly anticipate the future internal needs of your code, even if all the external design demands are known in advance (and that is rarely the case!), so it is foolish to try to design much up front. It is important to think about aspects of design when the time is right, and to keep things malleable. A code design document only adds friction to such processes.

Despite what I said, it is possible that, over time, documentation of the code grows in a way that an implicit code design document is created. However, this type of document is "good" because it grows alongside the code, instead of being there before the code.

I'm going to give an answer somewhat counter to the others.

It depends on the goal of the project. Some games are supposed to be technical achievements, and those should have more technical design documents. Some are designed to be story driven, and those should have story focussed GDDS. Some are designed to be more artistic and should be art focussed. Still others are designed around being competitively balanced. Etc etc.

Design your design doc around the goals/focus of the game. You shouldn't have any final code in there, but pseudo code or some system planning might be acceptable.

[color=#1C2837][size=2]Specifying interfaces in advance in some kind of design phase, giving them to two different teams that implement different parts of the code, and then putting things together is going to fail. What you should do is simply grow the code base from a minimal seed that does something useful.[/quote]
[color=#1C2837][size=2]This is actually a major part of software engineering. Softare design docs are written for pretty much this exact purpose. If an interface puts out what is expected for what you put in, and it meets performance requirements, it shouldn't matter how many teams are working on which parts.
[color=#1C2837][size=2]

[color=#1C2837][size=2]It won't work at all if you don't plan correctly, but not only will it not fail with correct planning, it's actually how it should be done in the first place.

frob++;

[color="#1c2837"]Specifying interfaces in advance in some kind of design phase, giving them to two different teams that implement different parts of the code, and then putting things together is going to fail. What you should do is simply grow the code base from a minimal seed that does something useful.

[color="#1c2837"]This is actually a major part of software engineering. Softare design docs are written for pretty much this exact purpose. If an interface puts out what is expected for what you put in, and it meets performance requirements, it shouldn't matter how many teams are working on which parts.

[color="#1c2837"]It won't work at all if you don't plan correctly, but not only will it not fail with correct planning, it's actually how it should be done in the first place.
[/quote]
The problem with that line of thought is that it assumes that you are able to plan correctly. I would argue that, as long as you are working on an interesting problem, this is inherently impossible. What do I mean by interesting? I mean it in a very subjective sense: interesting is what is new and challenging for you and your team.

If what you are doing is new and challenging for your team, this means that you probably don't understand the problem perfectly yet, which means that you are only able to guess at what the ideal interfaces are. It might turn out that your guesses are correct, and then you're very lucky. It might also turn out that your guesses are wrong, and then you're causing yourself a world of pain by working towards the specified interfaces. If you defined an interface J between two modules A and B that is not good for its purpose, then both A and B will have to work around the weaknesses of interface J, introducing shim code that is a likely source of bugs. Since there are so many ways of defining interfaces, I would argue that the likeliness of getting it wrong is relatively high in a situation where you don't understand the problem too well. It would be better to simply evolve A and B together with J at the same time, so that lessons learned while implementing A and B can influence each other and the interface.

If what you are doing is boring (in the sense of not interesting as defined above), i.e. you already understand everything about the problem, then you may indeed be able to specify interfaces perfectly in advance. Then again, if that is the case, why are you bothering with reinventing the wheel in the first place? If you understand everything about the problem, it means you have solved it before, or seen an existing solution, so why don't you just reuse and adapt that existing solution?

Ultimately, this is simply my take on the whole waterfall vs. agile debate.

[color="#1C2837"]Specifying interfaces in advance in some kind of design phase, giving them to two different teams that implement different parts of the code, and then putting things together is going to fail. What you should do is simply grow the code base from a minimal seed that does something useful.

[color="#1C2837"]This is actually a major part of software engineering. Softare design docs are written for pretty much this exact purpose. If an interface puts out what is expected for what you put in, and it meets performance requirements, it shouldn't matter how many teams are working on which parts.
[color="#1C2837"]It won't work at all if you don't plan correctly, but not only will it not fail with correct planning, it's actually how it should be done in the first place.
[/quote]

This one is actually a fun study.

Read the anniversary edition of the book "The Mythical Man Month".

The first edition called for what you described. A full specification of the implementation details. The implementation details specified by 'specialists' up front, and amendments required group consensus of the different leads, much like a surgical team with multiple core people and their supporting staff. This was a reasonable practice at the time.

It worked back in the 60's and early 70's because computer time was much more expensive that human time. Development teams had to rent CPU cycles, and their budgets were quickly depleted. Storage was paid by the byte. Going through IBM's 350 storage devices you could lease 4.4MB for the bargain price of $3200/month (in 1960's money). It made sense to spend so much time on the implementation details and big design up front because of the incredible expense of computer time. A single iteration on the implementation was very time consuming and expensive. It was more cost effective to have a half-dozen experts figure out the details, pass those to an army of secretaries who would type out copies of the details, bind the copies, and distribute them to each team's desk. Yes, they were typed by hand, the Xerox Duplicator machines were still more expensive than an army of typists.

A single code iteration with verification tests cost tens of thousands of dollars.

A single design iteration for a full waterfall design cost only a few thousand dollars.



The anniversary version has a chapter on things that have changed. Two of the new sections are "The Waterfall Model Is Wrong" and "An Incremental-Build Model Is Better". It reflects how things have changed.

Computer time and storage is practically free in comparison. The amortized cost of your computer and storage is pennies per day. Compare this with the potentially hundreds of dollars per day of the past.

Today, a single code iteration takes a few minutes of build time. With self-testing code and unit tests, you can get a fully verified build of a complex project in just minutes. Compare this with the tens of thousands of dollars and multiple work-months in the past.

A single design iteration for a full waterfall design of a complex system still costs a few thousand dollars. It is still a manual process, and human cost has increased over time.




There are rare exceptions. Certain features that require significant effort and costs still make sense. For example, it makes sense for the ISO language standards committees to spend years developing the language specifications because the cost to implement the changes is in the billions of dollars as it propagates.

Very few systems have such expensive iteration costs.

The most cost effective solution in modern software design is to specify the implementation details as late as possible, and iterate rapidly as they are discovered.

There are rare exceptions. Certain features that require significant effort and costs still make sense. For example, it makes sense for the ISO language standards committees to spend years developing the language specifications because the cost to implement the changes is in the billions of dollars as it propagates.

Very few systems have such expensive iteration costs.

The most cost effective solution in modern software design is to specify the implementation details as late as possible, and iterate rapidly as they are discovered.

Interesting. I haven't seen the new version of the book.

I was talking more along the lines of the code/implementation not being a function of the game features, but the game features being a function of a certain implementation. More of the case where you have a tech demo you want to evolve into a game.

A good example of what I'm talking about might be having an N-body simulation that has decent performance and thinking to yourself, "well that's cool. I wonder if I could make this into a game," then creating a GDD with other features. That might be more technical as the design has to fit the existing implementation.

I'm curious to know how the Crysis 2 and Rage GDDs work, as they are kind of technical showpieces for a new commercial engine.