newbie to design.
Author
I'm totally new to design and I can only begin to guess the different ways to do design documentation. I've spent years coding small and useful apps and now I'm doing my first big project. My particular troubles comes from the fact that I've done my first very large software program(15,000 thousand custom coded lines and growing), and it's becoming unmanageable.
I've talked to some friends for help, and they've told me to write a design and code documentation, and after some research I've become a total advocate of code and design documentation. I have doxygen set up and everything commented, and I've begun writing the design documentation for what I've coded and what needs to be done to finish this large project of mine.
I'm doing the design documentation in dreamweaver, and using php/mysql to help automate parts of the documentation such as a dev journal and task lists with varying priorities.
My design documentation for what I've already coded is in present/past tense, but the documentation for what needs to be done is in future tense. This seems really weird. How should I be writing this design document ion? Should I just give direction on how some concept should be implemented, and try to be time neutral?
And as I go on in this project, there will be a few more modules that I need to design and code to solve my software requirements, just because I don't have the current architectural skill to do a completely top-down design. There are many things i honestly can't foresee as i'm still inexperienced in game programming.
So my question is, "Is it wrong to have an evolving design documentation?". I'm making absolutely sure to add no more features to game, but sometimes I realize I need to add a whole new module to help supplement my intended solution to one of the features. Any advice would be greatly appreciated.. It's been troubling as I've spent the last week catching up on design and documenting and doing NO coding! I might of been able to be finished! Though maintenance would of been hell...
Thanks for any help.
Interesting question, documentation serves more than a single purpose, most of the time it can be used to inform others quickly about design features of a project. It is used as communication tool more than anything. If a particular element of a project is changed during the implementation, it is important to reflect those changes in the documentation so that others working on the same project are made more aware.
When implementing some software, in my view, it is an accepted fact that the design will need to change, due to unknown issues, such as technical limitations (hardware features, limitations of the implementation language). Also if you are programming on behalf of a client, they often change there minds during mid implementation, it is important whichever design methodology you choose allows you to reflect those last minute changes.
One could argue, that if you stuck to the original design all the way through the implementation and during the process you come up with new ideas, or better ways of doing something, those new ideas could then be implemented in the next version of your software product. However if you had too many suggestions and ideas during implementation, one could also argue that the original design was wrong and needed more development. basically, you are never going to have the perfect design first time out, the real question is "how are you going to cope with the inevitable need for change?"
Of course, this all depends on which design methodology you have chosen, some have a more rigid structured approach, whilst others are more loose and flexible. Its important to use a methodology you feel most comfortable with, and most appropriate to the given project, otherwise you'll soon lose the will to update the documentation.
When implementing some software, in my view, it is an accepted fact that the design will need to change, due to unknown issues, such as technical limitations (hardware features, limitations of the implementation language). Also if you are programming on behalf of a client, they often change there minds during mid implementation, it is important whichever design methodology you choose allows you to reflect those last minute changes.
One could argue, that if you stuck to the original design all the way through the implementation and during the process you come up with new ideas, or better ways of doing something, those new ideas could then be implemented in the next version of your software product. However if you had too many suggestions and ideas during implementation, one could also argue that the original design was wrong and needed more development. basically, you are never going to have the perfect design first time out, the real question is "how are you going to cope with the inevitable need for change?"
Of course, this all depends on which design methodology you have chosen, some have a more rigid structured approach, whilst others are more loose and flexible. Its important to use a methodology you feel most comfortable with, and most appropriate to the given project, otherwise you'll soon lose the will to update the documentation.
One thing that's important to realise, which echos what moosedude has said, is that design is an iterative process. There's no such thing as designing something entirely upfront and then ploughing through the implementation.
If someone tells you otherwise they're either
(a) kidding themselves
(b) an employee of NASA
Because of this, I tend to create a rough design up front, a few UML-like diagrams here or there perhaps, describing key interactions. As I start to implement it, I make sure that the current functionality and interface is well documented (e.g. doxygen comments) at all times.
Once the implementation has "stabilised", I then go back and update any diagrams etc that I made in the first place to reflect how the design actually turned out.
I've also found it useful to set up a personal wiki on my machine where I can toy with ideas, which helps with design and documentation.
Edd
If someone tells you otherwise they're either
(a) kidding themselves
(b) an employee of NASA
Because of this, I tend to create a rough design up front, a few UML-like diagrams here or there perhaps, describing key interactions. As I start to implement it, I make sure that the current functionality and interface is well documented (e.g. doxygen comments) at all times.
Once the implementation has "stabilised", I then go back and update any diagrams etc that I made in the first place to reflect how the design actually turned out.
I've also found it useful to set up a personal wiki on my machine where I can toy with ideas, which helps with design and documentation.
Edd
If you're using a software lifecycle model such as agile, then you're looking at "releasing" iterative, working versions of your application in relatively short time increments. In this case, yes, your design is going to change alongside it.
A solution is to keep your design, SDK docs and so on in version control alongside the source code, and before any major version ensure the docs reflect the current state of the system.
Personally, I write design docs in future tense and SDK docs in present.
e2a - the wiki idea is great too, the last two companies I've worked at both used them, though generally for more informal documentation such as "how to use this part of the animation system", "what to do when source control is borked" and so on. I'm sure it'd work for more formal SDK docs, but if you have doxygen setup I'd stick with that :)
A solution is to keep your design, SDK docs and so on in version control alongside the source code, and before any major version ensure the docs reflect the current state of the system.
Personally, I write design docs in future tense and SDK docs in present.
e2a - the wiki idea is great too, the last two companies I've worked at both used them, though generally for more informal documentation such as "how to use this part of the animation system", "what to do when source control is borked" and so on. I'm sure it'd work for more formal SDK docs, but if you have doxygen setup I'd stick with that :)
If your code is unmaintainable now, you should immediately begin refactoring as well as doing design.
Refactoring makes sense -- you can take a day or two off to clean up your code and save you weeks of effort in the future.
Refactoring makes sense -- you can take a day or two off to clean up your code and save you weeks of effort in the future.
Author
moosedude: Thank you for your reply. I'm glad to have confirmation that a flexible design isn't a bad once, it's just a choice and I like your recommendation of doing what's most comfortable.
For some reason a lot of newbies hear this from somewhere and then they tell other people this. This is where I got the idea, and I could never feel comfortable doing that. I'm glad to hear what I thought is a fallacy is a fallacy.
fsm: i dont know much about agile, but I do like having a dev journal for more informal documentation. Often my actual documentation will link to some dev jouranls entries that give an informal rational for a design decision.
Ravuya: Yes I definitely agree, just like writing literature, i've learned revising/refactoring is part of good programmng. One of the best things about my design is that it has brought a clear structure to several of modules that I implemented more intuitively and they weren't so well thought out. This has made refactoring a lot easier. I've also been finding many pieces of code that are nearly identical and I find that i can refactor the code into one code piece, with a variable for whatever where I had some constant.
Maybe this is true only if you're only a beginner, but it seems like sometimes the first solution I write, is like a rough draft. The logic is very well thought out, but the code is far from elegant. After a few more revision the code is like a final draft, and is beautiful, concise and very powerful.
Quote:
the_edd
There's no such thing as designing something entirely upfront and then ploughing through the implementation.
If someone tells you otherwise they're either
(a) kidding themselves
(b) an employee of NASA
For some reason a lot of newbies hear this from somewhere and then they tell other people this. This is where I got the idea, and I could never feel comfortable doing that. I'm glad to hear what I thought is a fallacy is a fallacy.
fsm: i dont know much about agile, but I do like having a dev journal for more informal documentation. Often my actual documentation will link to some dev jouranls entries that give an informal rational for a design decision.
Ravuya: Yes I definitely agree, just like writing literature, i've learned revising/refactoring is part of good programmng. One of the best things about my design is that it has brought a clear structure to several of modules that I implemented more intuitively and they weren't so well thought out. This has made refactoring a lot easier. I've also been finding many pieces of code that are nearly identical and I find that i can refactor the code into one code piece, with a variable for whatever where I had some constant.
Maybe this is true only if you're only a beginner, but it seems like sometimes the first solution I write, is like a rough draft. The logic is very well thought out, but the code is far from elegant. After a few more revision the code is like a final draft, and is beautiful, concise and very powerful.
The first time you do something, you don't know what you're doing. The second time, you do know what you're doing, because you did it before.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement