code comments

[FSM with Cheddar]

Read CodeComplete2. It is the bible for programmers on this subject.

In summary:
Comments should not be pseudo code.
Comments should not paraphrase code.
Comments should add value to a code section, where it is not immediately obvious to a competent programmer what is going on.

 

[ratewhore]

RW is not a nice chap. I bet he's an agent.

Bless. This is general, you have to take the rough with the smooth...

 

[Drewster]

Read CodeComplete2. It is the bible for programmers on this subject.

In summary:
Comments should not be pseudo code.
Comments should not paraphrase code.
Comments should add value to a code section, where it is not immediately obvious to a competent programmer what is going on.

(Serious mode on) - Good advice.... (SM off)

(Less SM on)
I am a competent coder (so my comments are great/not needed).
He is a donkey (so his comments are pointless and his code is tulip and he isn't fit to read my code)

 

[VectraMan]

I pride myself in being good at delving in and figuring out other peoples' code, but I know from experience not to pay too much attention to either comments or documentation. They're typically either plain wrong, or incomplete, usually written because the programmer was told to and not checked by anybody else for usefulness.

Current ClientCo. want me to write a comment block at the start of every function with a change history of that function. I've made the point that that's what source control is for, but they haven't changed the policy yet.

 

[swamp]

Comments are bad

Comments are bad

Developers should write little or no comments. Comments are bad and often lie.

If you want to know what a class does look at its unit test.

You DO all write unit tests...?!

 

[Mich the Tester]

Developers should write little or no comments. Comments are bad and often lie.

If you want to know what a class does look at its unit test.

You DO all write unit tests...?!

Please don't tell programmers to test. Their bugs finance Tester Manor.

 

[minestrone]

Actually the most annoying ones I find are..

// Fix for bug #196, Fix By Joe Bloggs, 12/12/03

I want to take people outside who do that and beat them about the head with a CVS manual until they know what a repository is used for.

 

[swamp]

Current ClientCo. want me to write a comment block at the start of every function with a change history of that function. I've made the point that that's what source control is for, but they haven't changed the policy yet.

What happens when you need to merge two functions? Or delete one? Or refactor one out into a bunch of new classes and functions as part of a pattern?!

 

[FSM with Cheddar]

Someone I know cut and paste some code from the internet (including comments) and put it in production code. The comments were in Spanish, but he thought he better leave them in.

During testing it was found that the code didn't work. After putting the Spanish comments through google translator it came out as "This code is an example, and I can't get it to work, not sure why"

 

[Moscow Mule]

All you chaps with your new fangled languages (C ? wtf is that?) should try decyphering RPG2 without comments.

It's a complete cluster****.