I was just wonder how much actual documentation of source code do you (the person who is reading this) use?
George Gough
ID:151960
 Aug 5 2008, 5:07 pm
|
|
I don't normally use any documentation unless it's something really complex. The only thing I do is put notes so if I stop coding a system, I know where to pick back up at.
| |
Documentation on a big project is well common sense so you don't lose things.
Personally i never document anything in any project since i am a "neat" freak all my functions are in a certain file a certain area etc. But if it was a lib/demo i would document all of it otherwise whats the point of giving it to people when they have no idea what so ever. | |
For my libraries, I generally have little, if any, documentation on the actual source code. I generally put documentation on what things do and what they're for in a seperate file (generally +Documentation.dm), and that gets very detailed. Without downloading any of my libraries, you can see this on my forums, as I make it a point to post the documentation on the post that announces the libarary's release.
| |
I document the purpose of functions if its not obvious where or how the function should be used. If a sub-part of a function is complex enough I document the purpose or reasoning for it.
I also stick // TODO: tags around my code if I go to bed or leave something in the middle of tweaking it. // DEBUG tags go after code which is only meant to help debug things, so I can remove it again afterwards. I also document the general purpose of a file at the top. Documentation is your friend. Coming back to something years (or months) after writing it can be tough without it, because what seemed logical at the time won't seem logical now. Of course, the amount of documentation needed really varies depending on personal taste and code complexity. I never document anything to do with language basics or syntax | |
KodeNerd wrote:
I was just wonder how much actual documentation of source code do you (the person who is reading this) use? I don't document anything unless it's a library I intend to release... and even then, my ability to remain accurate and helpful with comments is questionable. I usually end up deleting the comments from the file after a few updates when they no longer reflect what's actually going on. There are several instances where I probably should at least stick a few syllables in a comment for future reference, but I'm pretty good at deducing what's going on with or without documentation, especially if it's my own code. There are a rare few notable exceptions, though, and that's when I establish the "if it isn't broken, don't fix it" approach. | |
I've been considering implementing this for a while:
http://www.byond.com/members/Jp?command=view_post&post=29324 | |
code goes here //FIX!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!On test code (like increasing the probability of something to 100).