This question is kind of a two-parter. I have two types of documentation I'd like to discuss:
A) Design DocumentationB) Code DocumentationA friend of mine is also into Game Design, and I noticed something that's quite different between us; he seems to do detailed documentation both for his code (commenting more lines to improve readability, etc.) and his design (keeping in-depth design documents for most aspects of a game he'll be working on).These are both things I have never done, either for laziness, a lack of organization, or some other reason (perhaps a combination).Does anyone here keep documentation for your projects? Would you consider it to be important, or do you think it makes any difference at all?
If theres a reason for other people to use your code (and you don't hate them) then commenting is useful for helping them figure out what you were doing.
Whenever I code, I usually only comment if I think it's something I will have a lot of trouble remembering later.Makes sense. Both personally and professionally, I'm generally the other person to touch my own code, so I don't really comment.
What about design? Or do you not deal with that at all?I document my own code not only because I forget everything, but because everything I do is open source.
It's crappy documenting, but it's something xDIf other people are looking at it or you want to revisit it at a later date, yes. Otherwise don't bother.
Hmm… so we have a good amount of input on the code documentation side (thanks guys), does anyone have anything to say on the design documentation side?
What language are you using?
Code documentation goes together with coding style. No matter what you do, document your code, you never know when are you going to pick it up again, or if eventually someone else will have to do something with it.Lots of comments does not equal readability. Too many comments actually hurts readability.I don't get what you mean with 'design'. Is it design as in how the game will work (I want a shiny monster!) or as in implementation (how will we code the monster?)Like… putting down information about all the different aspects of the game. Things like this:
"The dagger is fast, combos well, but does very little damage. However, every time you attack with your dagger, and hit an enemy, your gun's charge level will increase."Later he goes into detail about the damage of each attack. Then he does the same thing for the gun; description and technical details.I see. I think both are equally important, specially if you're working on a team. Documentation, of any kind, is a way to communicate with your teamates,and communication is primordial to a successful team project. More information available for everyone equals faster development, less questions and in general less problems.
The amount of documentation is proportional to size of people working on something really. Big developers of hundreds will hire people who just write specifications that explain every detail, while teams of one or two people can just write down only what they might forget and communicate ideas face to face.
I make notes about "This is here because of x" and "If you remove this everything explodes." Other then that I have zero documentation for my code.