Code comments:How much is to much

[everfornever]

Hi guys, I was wondering about code comments, i know flash skips over them and all, but is there a limit were this starts to affect it's speed?

Like if I am writing a tut for say, and I have a code of 500 lines but ehn I got like 1500 lines of comments, so now it's 2000 lines of code, does this start to affect it's speed at all?

May be stupid, but I only have to assume either flash does not see it at all, or see's it and chooses to skip it, the later I could see taking cpu power.

[VENGEANCE MX]

If you exported a .fla full of comments, then decompiled the .swf, there'd be no code in it. They don't make it into the final file.

I personally only use comments to 'comment out' snippets of code that I want to disable temporarily, since I'm the only one who'll ever see the fla, and I know what every line of code does.

[everfornever]

Thanks buddy, thats what I figured.

You don't use code comments?

I use a crap load of comments all the time, I make huge blocks to seperate vars from functions, moves from attacks, player from enemy, the main reason i do it, is I hate that the autoformat also takes out line spacing,I like to be able to scroll quickly and find stuff, I like everything to be seperated.

That's just me, I'm still in the learning stages so I need to remmember what everything is doing.

Thanks for the heads up t hough VENMX

[mickm]

Everfornever,

I believe it all depends on what its for. If your trying to teach someone sure put comments in like crazy. You dont have to comment every line. They should be smart enough to figure some things out.

If its for OOP or reuseable code I believe it's always a good practice to put atleast what the function does. So if you ever need it for something you can always do a quick search.

If you are like vengeance and you are the only one looking at your code you probably will only want to comment the things you really need. (like hard functions to remember or something).

In my code the only comments I use are to separate my functions as i group them together.

[renderhjs]

also if you have a figured out a pattern of typical mechanics that work for you there´s no need to comment those things each time out.
If someone want to explain me a code I usually prefer slim code withou lots of explaination. Just some smal hints when something important is triggered or an important variable is stored.

[everfornever]

Well I have been using more comments than norml lately with lost, I try to put all the combat stats in comments, so later when I want to reuse it I know how I figured dmg/hits/crits and stuff.

I just wasnt usre if all these comments were compiled

[xtrava]

Well I use them to remind myself what I was doing there with that bit of code. But if you are very experienced then you probably dont need them to know what that particular code is doing.

However my current game I'm working on is a Uni project, and the script must be printed off when I had everything in, so it needs to be commented well for the marker/lecturer.

[Squize]

I've always been a heavy commenter, not to the point of every line, but anything which I know I'll wonder why I did it a certain way.

Most methods have an overview comment, eg

/**
 * @method houseKeeping
 * @description - Clears everything up after the player has been killed / level has been completed
 */

And I use it a lot as a kind of formal white space, to break the code up and keep it in sections,

//----------------------------------------------------------------------
// Start loading / parsing methods
//----------------------------------------------------------------------
methods in here...
//----------------------------------------------------------------------
// End loading / parsing methods
//----------------------------------------------------------------------

When you've got a couple of 1000 lines of code in one class / layer, then it makes hunting for stuff a million times easier.

I don't think anyone should fall into the trap of thinking that they can code without comments 'cause they'll understand it forever, I can't remember how I did things in the last project.
( When you're turning things around really quickly all the time, they really do blur in to one ).

Squize.

[trogdor458]

putting comments might affect compiling, or take up memory in your fla, but thats about it

i dont use comments (unfortunately i found a variable recently and i didnt know what it meant!! "obsc")
i like things to look nice and short as possible

[Squize]

Yeah but you're making your life ten times harder.

It's like using i,j,k etc for var names. Unless it's a local var for a loop, that's just insane.

Squize.

[trogdor458]

most of the time i use longer variables, it was just that one that i didnt get (i knew of its purpose though, luckily its not used much)

"obscure" comes to mind

use comments when you feel its neccesary

[trogdor458]

c***, i need to not click "post quick reply" more than once
srry about the double post

[VENGEANCE MX]

I can usually tell what a code does by the shape of it. Commando 3 developed my 'sixth coding sense', and I was able to scroll through 7-8,000 lines of code without reading any of it, just looking at the indentations and where the lines ended. That was enough to tell me what the scripts did.

Can anyone else here do this, or is it just a by-product of my autism?

[Squize]

Don't get me wrong, I used to be able to do that, used to be able to do it with assembler!

Perhaps it's age, or perhaps just the sheer volume of stuff I've done the last couple of years, but really need to comment stuff up.

Squize.

[trogdor458]

I can usually tell what a code does by the shape of it. Commando 3 developed my 'sixth coding sense', and I was able to scroll through 7-8,000 lines of code without reading any of it, just looking at the indentations and where the lines ended. That was enough to tell me what the scripts did.

Can anyone else here do this, or is it just a by-product of my autism?

i wouldnt know, ive never had that many lines of code all in one place
or are you dramatizing?

you dont use 6 senses for coding, you dont even use 5 (i dont recall ever "tasting" the computer)

[VENGEANCE MX]

Trogdor, the use of 'sixth coding sense' was to imply that I have the first 5 senses, but my sixth is one which helps me code. And no, I'm not dramaticizing, you can get a general feel for it even with a few hundred lines of code.

[cadin]

I happen to be reading about this very topic right now. From The Practice of Programming:
"When it takes more than a few words to explain what's happening, it's often an indication that the code should be rewritten."
"Comments are meant to help a reader understand parts of the program that are not readily understood from the code itself. As much as possible, write code that is easy to understand; the better you do this, the fewer comments you need. Good code needs fewer comments than bad code."

I think it's pretty solid advice, although it's much more easily said than done.

[tidenburg]

Like Squize said, I always comment section of my code for easier navigation. In my flash program i've also set the comment colour to dark red so its easier to scroll past and see where a section ends or starts.

[nGFX]

I usually comment the class header to give an overview what it's all about, along with some general info:

/**
* Pathfinder class
*
* @description find a way between 2 points in a 2d boolean map
* 
* @author	nGFX
* @version	1.1
* @changes	1.1 	added storage for the last path
* 					init method
* 					constants for Level
* 			
* @date		29/10/2006
**/

class Pathfinder {...}

... and functions inside the class:

/**
*	inits the Pathfinder
*	
*	@param	aMap	a 2d boolean map array, true is an empty field
*	@param	pStart	an Object containing x and y postion of the startpoint
*	@param	pEnd	an Object containing x and y postion of the endpoint
*	@param	iDepth	maximum length of the path
*	@param	iLevel	search depth, the smaler the number the faster (0, 1, 2)
*/
public function init (aMap:Array, pStart:Object, pEnd:Object, iDepth:Number, iLevel):Void { ... }

while comments inside the code only comment things that are not obvious or need to be done later, like:

// find empty, NOPing baddy
for (i=0; i<this._objGame.aObjEnemy.length; i++) {
... // some 20 lines of code
}


if (this.bFlipFlop) {
   this._Game.checkEnemies();
   // ToDo: check time, update HUD
}

somethimes I use comments to seperate blocks of code, as they are not really needed but help to maintain readability in larger functions (with lots of code that cannot be reused, as in initing methods):

// set up the baddies and hide them ...
... // some lines of code

// init the pathfinders and set up the trackers ...
... // some more lines of code

nGFX

[The Helmsman]

Personally I found that there are no too much comments in your programs.

Especially when you come back to work on some project you've involved a couple of months ago