comments in scripts

[sandyrepope]

I would like to know something...... When do you put comments in your scripts?

Do you do it as you type in a script or do you wait until the script is finished?

If you do something else than what is in the above question could you explain it?

I'd really like to know what is the best way to handle this.

Thanks
Sandy

[ErosOlmi]

I usually comments while I write the code. Whatever language I use.
I prefer doing it immediatelly because my mind is concentrated on the specific point. If I'm in hurry, in any case I set a little comment in some critical points.

[E.K.Virtanen]

If i am creating a bit longer code than 10 lines, i will comment it while im working with it.
I often comment short codes (less than 10 lines) at start to describe what that code does.

I comment code blocks (function, sub, data structure, etc.) and when there is some tricky algorithm which might be hard to remeber later.

Generally i think it is good to comment while working and not to wait until code is finished.

[RobertoBianchi]

Trick: ThinAIR has a special feature to speed up the inclusion of the date, time and signature that could be usefull for comment, try it from menu EDIT\INSERT\DATE, TIME AND SIGN.

Roberto

[kryton9]

A great way to start for me for bigger projects is to write the comments first and use it as an outline of what I want and then go fill in the parts with code.

Another thing I do in thinBasic and now see that is frowned upon in c++, I group all my variables as much as I can in few locations, for example I put all my global variables together. My user defined types all together. I try to place the local variables at the top of the routines or sections. This is sort of how you do it in Delphi and I sort of liked it and carried it over to thinBasic and it worked well I thought.

I see Petr codes as they recommend in c++. You declare and define the variable when it is needed and not before. This seems strange to me at the moment but I can see in c++ where it is the way to go, but in thinBasic, I am not too sure.

[Petr Schreiber]

Hi,

I usually comment the code when doing difficult parts, or frequently when I know code will be used by something else.
Bit of self documenting is hidden in my inclination to give functions and variables longer names, I know it makes lot of people scared :))

I think it is better to comment as writing the code, rather than adding comments additionaly. That way you can un-intentionally add comment which does not exactly match what code does.

Kent, how do you mean my C++ variable declaration disease? :D

I used to had longer "columns" of variables and TYPEs when developing TBGL, but then I realised it is difficult to read through it so I split code in parts, each having its "variable initialization" section. This is essential when writing some kind of garbage collector and similar - you know which parts allocate what, so you can keep an eye on proper deallocation too.

In fact the code is still the same on the beginning, just split in smaller code dwarfs, which have similar structure but all in smaller bits. It is kind of source code fractal :D

I think it is ok in thinBASIC sources. As thinBASIC creates dictionary of functions in real time, I think it is better to not fill it with variables I might not use on the end, so this per partes approach can lead to better performance. Could. I think. Sure it can have some side effects ... cannot imagine which now :)


Bye,
Petr