Comments
Author: | Muz
|
Submitted: | 17th November, 2008
|
Views: | 4888
| Rated: |
|
|
From all the coding I've been doing, I've realized one thing: Comments are your friend. Use them. It could take half an hour to understand your code a few months from now, but only half a minute to jot down a long comment.
Here's a quick guide of what I do with them. You don't have to follow me, but they've worked for me and could work for you.
To Do list
I find that at the start of every project, it's good to toss a to do list in the project. With a large project, you'll have so many things to do that you'll get confused with what you're supposed to do next. A to do list makes everything so much simpler - you no longer have to juggle all those things to do in your head anymore.
I put my To Do comments at the bottom, sorting them by what I want to do next. Sometimes I toss them into their own event group.
Bug list
As above, but I put them at the end of every event group to list everything that needs to be fixed. If I don't know where the bugs are coming from, then it goes at the bottom.
Formulas
This is important. My game usually uses a lot of formulas or weird engine handling. Formulas are very difficult to read in the expression editor. Trust me. If you have any formulas taking at least 2 full lines in the expression editor, make sure you comment it!
Also, there are times when I use someone else's or even my own engine or code. For those cases, I comment where the original engine is, or jot down what it does overall. Or generally if it looks weird, like some of the workarounds Pixelthief suggests, I comment what it does.
Color coding
Tigerworks suggested using colors to tell how old the code is. That helps for future debugging, but I prefer to do it like this:
Light grey - Comments, formulas
Light grey is good on the eyes if you're using the default color scheme. It keeps the comments subtle but legible.
White - Take action
These are things I want to come back to in the future. White sticks out, so it's good for jotting down a bug or something that needs to be improved.
Red - Take action ASAP
Red really sticks out. This is what I put for a high-priority bug, a section of the code everything relies on, or a formula I haven't finished coding but feel too tired to finish.
Don't mark everything as red! That makes you confused on where the next step is. If you have a series of bugs, use the To Do list. If you have a major bug somewhere, maybe make it light pink or so.
Dark grey - Obsolete code
Often, I find a better way to do something, like a loop which cuts down my code by a quarter, I add a dark grey comment on top of it, telling how the code could be improved. Then, if I feel that I have to edit the code, I could then re-do it to the new method.
This is because often, there's a lot of obsolete code which doesn't need to be fixed, but it will be a bit of a bother if you don't note down that it needs to be fixed.
Etc
Sometimes I get bored of the ticks in the event editor, so I change it to a smiley face. Or an angry face when there's too many bugs. Yeah, it's not very useful, but it helps relieve insanity when you're annoyed with a section of the code.
|
|
|