Summary

Comments: How, where, why.
Comments are an invaluable part of Clicking and are absolutely essential! My current project would be absolutely nowhere. I know a lot of you who don't comment will look at this and think 'Yeah right, what a load of rubbish', but really, they are useful. I'll try to describe why.


Comments: Why?

Why comment?

Well, in my current project, Terminal Orbit, the code is long, complicated and uses around 15 of the alterable values. Trying to modify code which I wrote a month or two ago on the same game can be a nightmare without comments. What is value F? Why does it put that flag on? Why on earth does it destroy that invisible thing there? Even just one simple comment at the top of a bunch of events doing one thing can provide invaluable help. 'Calculate angle' at the top of five events will suddenly make everything make sense when without those two simple words it could have been a cryptic mass of events.

Also, if more than one programmer is working on your game, how are they meant to know what your events do? Comments will explain and tell all.


Comments: How?

Wirte your comments as if you are explaining the working of the events to someone else - even if you are the only programmer working on your game! It makes so, so much more sense when you come back later to have a complete explanation.

I make my comments black background with white or green text. This makes them stand out more from the events and I find them easier to read, and gives the whole event editor a 'Cleaner' look. Copy and paste comments to save yourself setting the colours over and over again.

A good tactic I have just started using: Colour code your comments. Not on the difficulty of the events - thats only really to do with examples. Colour code on WHEN you did the events. For example, every week change from white to green to blue colours etc. Then, you can quickly see how old an event is and if it needs updating. Once you update an event, recolour it's comment to the current colour scheme.


Comments: Where?

In as many places as possible! Preferably every event, but that is not always a necessity. For example, to comment four events which are exactly the same but with a changed number somewhere is a waste of time and space. The extra comments will get in the way. Instead, just put one comment at the top of the four saying something like 'Range detection' or whatever (but the more detailed the better). Mention also how the coding works - which values are passed where through which alterable values and flags. It helps a lot.


Summary

- Comment at least every bunch of events which do a similar task.
- Write them like you're explaining it to someone else.
- Colour comments to suit your tastes.
- Colour coding by date is helpful.
- Comment as much as possible, and in as much detail as possible!

Trust me, especially on big projects, you will be completely baffled coming back at old untouched code in your game. It will waste time, effort and thus delay the release of your game! Just at least a few comments here and there will make everything make sense.

Happy commenting!

- Tigs


P.S. Sorry about the bad pun on the title