next »

[Aik]

I've just realised that the only time I've ever easily finished a program where it worked and didn't make my brain explode trying to trudge through the hell that was my code is when I sat down and planned it all out with lots of pseudocode and notes and suchlike.

Apparently I didn't learn from this positive experience, but I think I'm slowly getting the point - even if it has to be hammered in one failed project at a time. I may deliberately ignore everything my software engineering courses have to tell me (because I think I'd give up even faster if I had to actually use any of that shit) - but it's hard to argue with first hand experience.

So - to make this thread about something rather than my personal revelation - how do you plan out the code of your projects? How comprehensive does the plan have to be before actually coding?

[Alex May]

At the moment, our planning for Dyson is quite loose, by professional standards. We meet, discuss what tasks we need to complete. That is quite exhaustive - we try to think of everything. We write this down in a task document. Then we take each task and discuss what needs to be done to realise the task. We end up with a list of subtasks and maybe sub-sub-tasks etc that need to be completed - both code and design tasks, and whatever else, stuff for the musician or art tasks whatever. After that we go through and put rough estimates against each task. Professionally-speaking, I would be more satisfied with a technical design or description for each task that more clearly examined where the time estimate came from, but since we don't have as stringent deadlines as third-or-higher-party developers whose publishers impose strict deadlines, it's slightly less of a priority.

I don't have a technical design document or anything like that, but we do have a production document that details the game design. We also have a bug list that we keep up to date. Both the task list and bug list are kept online at google docs. I am considering deploying an existing bug-tracking system, and found one that might be OK, but I still haven't found a free system that can gracefully track both bugs and tasks in the same system. It's either task management or bug tracking, and I think the two are kind of interlinked and could be represented in the same system. Anyway I'm thinking of using bug tracking software soon.

If I planned out the things I had to do, technically, then things would probably go very smoothly, but it would slow me down a bit, so I tend not to think too hard about things in advance. I do spend some time thinking about it of course, but I don't usually write it down or set up pseudocode for it unless it's a really bonkers algorithm I've never done before like the landscape code I did for tianxia, for which I have pages and pages of notes, pseudocode, diagrams, and stuff.

[Hajo]

So - to make this thread about something rather than my personal revelation - how do you plan out the code of your projects?

Sometimes. For two of my projects I did extensive planning, sketches of how graphics could be, class diagrams for the code ... overall it's been a few dozen pages of sketches, notes and diagrams.

For one it worked quite well.

For another project I definetely overdid planning and ended up with a 75 page document, which had a serious case of featuritis. It was unusable as design document, but still is a big source of (forgotten) ideas when I come back to reading it again. It didn't work out, but it was not wrong either.

My latest project though didn't have any planning. I tried to keep things as simple as possible, the code as readable as possible.

This also works.

How comprehensive does the plan have to be before actually coding?

I guess it depends on your skill and the way you approach projects. Overall I think planning is good, and can definitely help. But I also think, sometimes one gets away without a lot of planning ... maybe the plan is there, but not written down in such cases.

If you are not alone, but work in a team, you need more written plans, though, to communicate.

[Cymon]

I've decided to do a fairly extensive planning period and document the whole thing for ASCIIPortal. The response so far has been... non-existant. I may have over done it a bit.

[Chris Whitman]

So - to make this thread about something rather than my personal revelation - how do you plan out the code of your projects? How comprehensive does the plan have to be before actually coding?

I plan about two or three 'steps' ahead at all times, and have a vague general idea of where I'm going. However, I write almost nothing down.

If I start a project from scratch, I might tackle graphics first, in which case I start thinking about how I'd like to organize sprites and resource managers, then I might think about how I would compose those to draw scenes, etc. I know what I want to end up in the end, but I don't start by sitting down and hammering out a bunch of UML diagrams, and I don't recommend you do either -- it's an enormous waste of time unless you're part of a large team and even then I suspect it is still a waste of time*.

The trick is to write code that is reasonably extensible and accept that if you are working on a reasonably-sized project you will probably end up having to do some refactoring one way or another (although obviously you should try to limit the time you spend doing this). Write simple code that does simple things, and work iteratively. Try to replace planning with good coding practices that minimize the amount of planning you really need to do.

The only documentation I maintain now is a list of features that still have to be implemented and a second list of fixes and updates to existing code. According to XCode Assistant, my project has grown to 31 000 lines of code, and my documentation is about twenty lines.

* Anecdote: when I was working for the man (not Batman), I was asked to design an optional module for our company's largest product. I drew up a shiny document that got passed around to managers and some of our larger clients. Everyone liked it so much I was asked to do a whole bunch of them for additional features and such. By the time I was writing document number three, the project from document number one had already basically been shelved due to time constraints. The purpose of most design documents is not to assist in implementation, it is to get clients excited so you can drum up business, or to make it look to your boss (who doesn't really understand what you do) like you're doing something that justifies paying you money.

[ஒழுக்கின்மை (Paul Eres)]

I don't plan out code, I plan out the game. That might just be a minor distinction, but I don't really plan "how" to do things, I just plan "what" the game is going to have, and figure out how to get it in when I come to that point. My current Flash game's plan looks something like this:

TO DO

v0.04 - enemies
- introduce enemies, get one enemy sprite in and give it behavior
- make it so that pushing an enemy off screen destroys it and gives the player a point
- make it so the enemy can also push the player by moving into them
- if the player is pushed out they lose points as long as they stay out of the room

v0.05 - differentiate players
- make 3 click effects, one for each character, and make them selectable by pressing E or space
- indicate on screen which type of click effect is in use
- player player color vary by pressing E or space as well
- make player stats vary by pressing E or space as well, three sets of stats
- limit the number of captured rain particles

v0.06 - upgrades system
- costs points, enemies give points
- can upgrade parts of each ability: capture range, capture limit, and all kinds of stuff

[Hajo]

how do you plan out the code of your projects?

I found this approach useful (particularly if you like OOD/OOP):

1.) Name all the things in your project

This will be a list with words like "level", "map", "user input", "trigger" or whatever. Besides nouns, it's useful to also include verbs like "move", "shoot" and adjectives like "fast", "vulnerable" or "colored".

2) Group the words. Cluster them if they seem to belong together somehow, maybe draw labeled links between them to denote how exactly they belong together. Some words might be linked to/by more than one cluster.

Nouns are good candidates for classes, or class compounds. Adjectives are good candidates for interfaces, verbs are good candidates for methods or messages of the objects.

The clusters can help to indicate packages or namespaces, also visibility of objects to each other.

From here you can either dive into coding directly, or try to do more detailed system design. Be reminded, this is really a quick-and-dirty method, but it might help to get started.