When you hire a coder/programmer

If you are hiring a programmer on a freelance/contract basis do you expect to have all code eg css php sql queries commented?
Comments enable you or another coder to understand what a specific block of code does.
How many of you expect this as standard or how many of you would pay a little extra for the time taken (and saved in the future) to do this?

[BestXXXPorn]

100% YES on comments being included... and I'm a developer.

[Barefootsies]

Originally Posted by BestXXXPorn

100% YES on comments being included... and I'm a developer.

[BestXXXPorn]

I should add:

PHP code (or other scripting languages) should have every file, function, and method commented as well as blocks of code and complex conditionals...

CSS should be self commenting (i.e. good class names) Although I like to separate out blocks of CSS with comments so it makes it a bit easier to find the "area" you're looking for. I generally separate out the CSS classes by what page they are used on with general (site wide) classes having their own group.

I don't comment queries unless they are very complex... they should be self explanatory.

[Varius]

If you are hiring freelancers/outsourcers, you should not expect/assume anything.

You should make sure it's included in your specifications that all code must be properly commented/documented.

Cheers for that. Was just curious as to what other coders do or what those who hire expect.

[grumpy]

just one line in head of function and a few notes down the way

[EscortBiz]

yes 100%

[EZRhino]

Great thread, for all those reading this and dont know, good commenting is worth the extra bucks. Will save a lot of headaches in the future.

[mafia_man]

Originally Posted by BestXXXPorn

I should add:

PHP code (or other scripting languages) should have every file, function, and method commented as well as blocks of code and complex conditionals...

CSS should be self commenting (i.e. good class names) Although I like to separate out blocks of CSS with comments so it makes it a bit easier to find the "area" you're looking for. I generally separate out the CSS classes by what page they are used on with general (site wide) classes having their own group.

I don't comment queries unless they are very complex... they should be self explanatory.

Yes functions and methods.

Did I repeat myself?

[KillerK]

Originally Posted by Varius

If you are hiring freelancers/outsourcers, you should not expect/assume anything.

You should make sure it's included in your specifications that all code must be properly commented/documented.

Varius FTW!!!

[camperjohn64]

// Talk about how commenting is useful
I am a comment fanatic, and it has payed off when I look at code 4 years later and can understand it and modify it within minutes.

// Say something insightful tying life and code together
People comment their code like they comment their life - they either plan it as they go, or fuck it up without documentation and hope to fix it later.

[k0nr4d]

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

[mafia_man]

Originally Posted by k0nr4d

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

If you don't comment then you should document code. One or the other depending on how big the project is.

If it's some shitty PHP script to resize pics though I wouldn't bother. Also Python because the code reads like a book anyway.

[BestXXXPorn]

Originally Posted by k0nr4d

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

Just because something may seem logical to you and the flow of information is something you architected... it doesn't necessarily mean it's going to be logical to someone else...

The next guy that comes along may normally follow a completely different design paradigm or maybe they're just inexperienced...

Good commenting practices make code (however clean it may be) easier for everyone that follows after you.

[grumpy]

Originally Posted by k0nr4d

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

well said sir, hats off

[Serge Litehead]

the truth is
if you expect full documentation, add 30-100% to the cost of project. any respected developer will not put in time into documentation without being compensated for the time it takes document the code on tight budget projects. since most people demand usually functionality and fast results.

its good practice to comment things
but unless documenting included in quote don't expect it by default.

[Broda]

Originally Posted by holograph

the truth is
if you expect full documentation, add 30-100% to the cost of project. any respected developer will not put in time into documentation without being compensated for the time it takes document the code on tight budget projects. since most people demand usually functionality and fast results.

its good practice to comment things
but unless documenting included in quote don't expect it by default.

Exactly my words.

[woj]

Originally Posted by holograph

the truth is
if you expect full documentation, add 30-100% to the cost of project. any respected developer will not put in time into documentation without being compensated for the time it takes document the code on tight budget projects. since most people demand usually functionality and fast results.

its good practice to comment things
but unless documenting included in quote don't expect it by default.

</thread>

Originally Posted by Varius

If you are hiring freelancers/outsourcers, you should not expect/assume anything.

You should make sure it's included in your specifications that all code must be properly commented/documented.

Originally Posted by k0nr4d

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

[BestXXXPorn]

Originally Posted by holograph

the truth is
if you expect full documentation, add 30-100% to the cost of project. any respected developer will not put in time into documentation without being compensated for the time it takes document the code on tight budget projects. since most people demand usually functionality and fast results.

its good practice to comment things
but unless documenting included in quote don't expect it by default.

Full documentation? Who does that? Full documentation is different than well commented code... OP asked about commenting... not documentation.

I factor my code commenting time in with EVERYTHING I do... Nothing leaves my local dev environment without being well commented.

30% - 100% time? Try more like 10%... if that. (If you're talking about commenting)

Kool feedback guys. Thanks for this!!

[Serge Litehead]

Originally Posted by BestXXXPorn

Full documentation? Who does that? Full documentation is different than well commented code... OP asked about commenting... not documentation.

I factor my code commenting time in with EVERYTHING I do... Nothing leaves my local dev environment without being well commented.

30% - 100% time? Try more like 10%... if that. (If you're talking about commenting)

you have a point, basic commenting shouldn't affect cost much as well not much should be expected. My train of thought went on to larger scale somehow

[BestXXXPorn]

Originally Posted by holograph

you have a point, basic commenting shouldn't affect cost much as well not much should be expected. My train of thought went on to larger scale somehow

Then I definitely agree with your 30% - 100% time addition... full documentation is a pain in the ASS and takes forEVER... and it's outdated as soon as there's an addition unless you always keep it up to date... that's a REALLY rare case.

[cyber]

function a($input){
// please to be doing the needful
  ....
  ....
}

[Varius]

One more thing to note, when working with foreign programmers, you should normally ask them to comment their code in English, unless you only ever plan to hire developers of that same language.

I remember one particular project which I had to sort my way through plenty of code (CSS element names no less!) in Russian and Czech and it's not very fun (although I did learn some words)

[camperjohn64]

Originally Posted by cyber

function a($input){
// please to be doing the needful
  ....
  ....
}

HAHAHAAHAHAHAA, That is so true! Engrish or Indian coders sooo do this!

Originally Posted by Varius

One more thing to note, when working with foreign programmers, you should normally ask them to comment their code in English, unless you only ever plan to hire developers of that same language.

I remember one particular project which I had to sort my way through plenty of code (CSS element names no less!) in Russian and Czech and it's not very fun (although I did learn some words)

good point i didnt even consider that people would comment in their native instead of english.

i guess the main key points are:
reccomend commenting to your client
dont let your client assume you do commenting
add the cost onto your fee, which is probably less than 10-15%
comment in english, not russian :P

[EscortBiz]

Originally Posted by BestXXXPorn

Then I definitely agree with your 30% - 100% time addition... full documentation is a pain in the ASS and takes forEVER... and it's outdated as soon as there's an addition unless you always keep it up to date... that's a REALLY rare case.

i cant think of any project I did that needed full doc, basic comments a few words will do just fine, and only where the fuctions are not obvious

[k0nr4d]

Originally Posted by EscortBiz

i cant think of any project I did that needed full doc, basic comments a few words will do just fine, and only where the fuctions are not obvious

Exactly. Full documentation is if you are writing up an API for other coders to work with, not for explaining what a function called "getTomorrowsDate()" or something obvious.

[cyco_cc]

Originally Posted by k0nr4d

Im not gonna say im against commenting because its sometimes useful when something is done complicated or strange for some specific reason, but the fact is if someone cant figure out what a piece of code does from looking at it, they have no business editing it.

As long as you use self-explainatory function names and variables...

That's missing the whole point of commenting. Commenting is for the "why" not the "what". Take for example:

int x = 5; // Declare a new int and set it to 5.

The above is useless because you know what the line does. However:

int x = 5; // This is our initial case as our function is not defined for x < 5.


Is not useless because it might not be readily apparent that said function isn't defined for values < 5. This is a simple example and yeah, in production code there would probably be a line in the method like if (x < 5) throw new InvalidArgumentException(x); so one could infer the restriction on the input, but it should definitely be commented.

This is especially useful in the case of financial or technical software (what I develop).

[Sid70]

Originally Posted by holograph

the truth is
if you expect full documentation, add 30-100% to the cost of project. any respected developer will not put in time into documentation without being compensated for the time it takes document the code on tight budget projects. since most people demand usually functionality and fast results.

its good practice to comment things
but unless documenting included in quote don't expect it by default.

Bookmarked!