Helping people (ppl who post code please read!)

[Shockwave]

As one of the main aims of this place is to help other programmers learn to code, and I know most people are good at this, if someone asks for help on something it is a really good idea to fully comment and explain what is going on in the program.

I've noticed a few sources of late that could have been better explained.

Over complicated and un commented listings will have the reverse effect.

Cheers

[rain_storm]

Thats a good point I usually make liberal dose of commentry in my own code (even I could get lost in there) but its easier to understand whats goin on when things are explained in the code itself especially when the person on the other end is learnin a new technique.

[ferris]

commenting....gross!!!

I'll keep this in mind

[Shockwave]

Cool, as long as it doesn't stop anyone helping out and posting code it'll be even better

[ninogenio]

ill try shockwave but ive tried to comment my code but im just not very good at it half the time my comment just get in the way.

i dont really do tuts most of the time i put code up and say heres a func if its usefull to you then yous it if not then dont.
but i get your point

[Shockwave]

Some code is better than no code I guess but what I am trying to say is that it's easy for us to forget how it was at first, I think that you have to allow people to figure out some stuff on thier own but posting a whole listing with no comments or description doesn't really help a lot, in fact it can be demoralising for the person learning and it shows poor programming practice on the part of the person posting the listing.

after all how hard is it to do stuff like this;

OPTION STATIC  : '  FIXED SIZE ARRAYS.
OPTION EXPLICIT : ' ALL VARIABLES MUST BE DEFINED.

Through your program so that people can see the flow of it?

And as well as that, if you wanted to take up programming professionally, most companies will insist that you follow a set format for everything, even code indentation! I'm not advocating anything as anal as that, just if someone asks for help, it doesn't help to give them a listing on it's own, it should be explained.

If you find it hard to comment your listings, it's something you should practice doing. Trust me, it will make your code much more portable so you'll benefit too.

This can apply to most of us at some point I guess, so I will repeat, it's not a serious grumble, just a heads up to help the community as a whole.

Cheers

[ninogenio]

your right shockwave all the code i post for the purposes of the comunity from now on will be commented as much as possible

[Jim]

Fair point!

Normally the only bits of my code you'll find commented are the bits that didn't work first time and I had to comment it to explain to myself what I as trying to do...

Comments like this are totally useless though

Code Select Expand


/* calculate pi */
int calculate_pi(void)
{
...
}

or

Code Select Expand


int a = 10;
a *= 5; // multiply a by 5

since they don't tell you anything extra.  It's far better to comment algorithms and processes, not the individual instructions.

Jim

[benny!]

Some ppl also tend to give their method, funtions and variables a "speaking name"
instead of extensive commenting ...

For example they do

Code Select Expand

float velocity = 1.0f

instead of

Code Select Expand

float v = 1.0f    // velocity

[Stonemonkey]

Just make sure you don't lose the code in among the comments. IMO (even though I'm probably the most guilty of not commenting) indentation is far more important than an abundance of comments and if used with (as jim said) just algorithms and processes can make code easily readable.

[rain_storm]

I dont agree indentation may make programming somewhat more organised but indents do not replace comments. the only people who can make sense of uncommented code are those people that are more experienced in the language in which case they are not the targets for the comments. its the newcommers that stand to gain the most from commentation