Best source code comment

biko

http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered-closed

My favourites:
#define TRUE FALSE
//Happy debugging suckers



/* Please work */

CreepingDeath

/*
 This code is for development purposes and should NOT be used in production
*/

This comment & associated code was found after many years in production code.

E39MSport

Years ago in a production code stream I saw: -

# Warning, sh1t code ahead.

Pygmalion

In dragonplayer, a fairly basic video player included with KDE

#ifndef NO_SKIP_PR0N
 // ;-)
if( !(url_string.contains( "porn", Qt::CaseInsensitive ) || url_string.contains( "pr0n", Qt::CaseInsensitive )) )
#endif

The following code adds a video you watch to the "recently played list", so this (unless NO_SKIP_PORN is enabled) makes sure nothing in your porn folder finds it's way in there.

Ok admittedly only the ";-)" is a comment, but you need the context to appreciate it.

satchmo

My favourite, courtesy of I Get Your Fail...

// As long as all calls to this class are made from the same thread this class is thread safe.

Evil Phil

// does something

seriously.

OwenM

// the next bit is obvious really

seriously.

bobbytables

// I don't know what the following does, but if it's removed, the app breaks...

:eek:

marco_polo

I have come across variants of the following disturbingly often at work

// TODO: .... 

// Really ugly but ...

Usually followed by a firm and sincere, but inevitably unfufilled commitment to refactor or enhance said code.

satchmo

Found this in our codebase recently, in the middle of the math::Matrix class header:

...
 
/// Rotate a vector by the inverse (transpose) of the rotation component of this matrix.
void RotateVectorTranspose(Vector* v) const;

/// Rotate a vector by the inverse (transpose) of the rotation component of this matrix.
void RotateVectorTranspose(const Vector& src, Vector* dest) const;

/// Unfortunately this function is only available to those who believe.
void ThereIsNoSpoon(void);

/// Builds a perspective projection matrix - same as D3DXPerspectiveFovLH
void BuildPerspectiveFovLH( float fovY, float aspect, float zNear, float zFar );
void BuildPerspectiveFovRH( float fovY, float aspect, float zNear, float zFar );

...

No idea how long it's been there. Needless to say, there's no implementation in the .cpp file.

mark renton

/**
* This app was created on 23/5/2003 by xxxxx xxxxxxxx john47832
*
*
*
*
*/

copacetic

//this is exactly what we said we wouldn't do, but the elegant way doesn't work.

DecTenToo

two

ONe in a rather convoluted set of CICS Cobol apps converted from another system

* Beyond this point be dragons

and a standard one for VB 6 and below (But not really a comment)

On Error goto pub

Sparks

The FIXME comments are usually the funniest. Looking back over some old notes:

// FIXME: what do we do here?

// FIXME: the following line is scary.

// FIXME: the following 2 functions totally suck, are useless and should be replaced immediately.

// FIXME: Do we care about revision? We should.

// FIXME !!!

// FIXME: add comments

// FIXME: come _on_ <coder's name deleted>, you can do better than this ;-)

whiteshadow

sneaky..!
[PHP]
// put hard limits on the year - nothing in the future for us!
[/PHP]

Steve

else
       'this will never happen
endif

CuLT

[php]
if(empty($unix_date)) {
return "Bad date"; // careful Indy!
}
[/php]

fasty

Not strictly a comment... I need to stop using Ghostbusters references in my debug output strings.

HWND hWnd = CreateWindowEx(
	0,
	window.GetWindowClass.Title(), 
	window.Caption(),
	WS_OVERLAPPEDWINDOW | WS_VISIBLE, 
	CW_USEDEFAULT, 
	CW_USEDEFAULT, 
	rect.right - rect.left, 
	rect.bottom - rect.top, 
	NULL, 
	NULL, 
	hInstance, 
	reinterpret_cast<void*>(&window));

if(hWnd != (HWND)window) 
{
	TRACEF(L"What did you do, Ray?\n");
	return 0;
}

hare05

Wrote this one myself in a Java method

// The important bit

And later in the same method

// The really important bit

And at the top of the class

// Abandon hope all ye who enter here

I think I lost 4% of my project grade for those.

boobar

The best or worst I've seen is

// Be careful with the following code in production for it does not do what it seems to do

Civilian_Target

//If you're looking for the cross sell flag, it's in the context.
//The boss told me it was ugly to put it in the request, so I hid it there

.

jebuz

in a Spring XML config file...

<!-- TEST WIZARD'S SLEEVE CONTROLLER -->

MrsJohnMurphy

not a comment but I once got bored using i,j for nested for loops all the time, so I started using the names of bands etc that I linked ...

int frank, black;
for (frank=0; frank<=maxa; frank++)
for (black=0; frank<=maxb; black++)

wasted over a day with the subtle bug introduced by the sloppy cutting and pasting

:cool:

mjm

lil_lisa

Just came across this on a website:

<!--
__ _.._
.-'__`-._.'.--.'.__.,
/--' '-._.' '-._./
/__.--._.--._.'``-.__/
'._.-'-._.-._.-''-..'

BACON.

__ _.._
.-'__`-._.'.--.'.__.,
/--' '-._.' '-._./
/__.--._.--._.'``-.__/
'._.-'-._.-._.-''-..'

GET IN MA BELLY.

-->

I'm sold on that company!

Hmm, it actually doesn't come out as good on boards...but you get the idea!