Source code comments, fun or profound.

[CORed]

I do that all the time.

I usually put "This should never happen".

 

[Paul C. Anagnostopoulos]

I usually put "This should never happen".

Heck, every ASSERT statement is basically saying that.

I just checked a compiler that I wrote a couple of years ago. The code includes 55 ASSERT statements.

~~ Paul

 

[SkepticScott]

One of 12 comments in a 1000-line module I was code-reviewing was something like:
//#include <stdlib.h> fix this!


Another time a contractor was helping us with a custom interface library for a customer. The customer got the source code. This was a very good, very big customer that we'd worked with for years and planned on working with them for many more years. The customer requested a change, and the contractor checked-in the changed code. It worked fine.

A couple releases later, after the source had been sent to the customer once or twice, I noticed the change was commented with
/* Because the stupid customer said so */

I verified that that comment was checked in by the contractor with the VCS, then I showed the product manager. A couple minutes later a VP was on the phone apologizing to a customer's VP while HR fired the contractor.

Be very careful with your comments!



The most fun I've ever had while writing a comment was a comment for a highly-optimized bit of assembly language that clipped a signed int to the range [0,999] with only one conditional jump and four other instructions.

;Clip the position in r0 to [0,999]. r1 holds 999 for speed.
; Deep magic. You do not need to understand how this works.
; But if you do, here is how it works

That was followed by examples showing the flow and register values for r0=-1, r0=50, and r0=2000. I don't think that code will ever change.

 

[Paul C. Anagnostopoulos]

One of 12 comments in a 1000-line module I was code-reviewing was something like:
//#include <stdlib.h> fix this!

I demand a list of all 12 comments. I can't wait ...

~~ Paul

 

[SkepticScott]

I demand a list of all 12 comments. I can't wait ...

I wish I could oblige you, but I don't remember them all. I think one or two were actually useful.

 

[theprestige]

I'm trying to remember where I read about this--Joel On Software, maybe?--anyway, a programmer who, on long projects, would place a "you are here" comment in his code whenever he took a break from coding, so that he could more easily pick up where he left off when he returned.

ETA: Presumably, unlike my own personal experiences with programming, the last function he touched didn't haunt his every waking thought (and most of his dreams) from the moment he left the code until the moment he returned.

 

[a_unique_person]

I like the redundant comments.

"Loop through the input till it's all processed." type of stuff.

 

[Paul C. Anagnostopoulos]

I like the redundant comments.

Or even:

        LD      X                       ; Add 1 to X.
        A       =1
        ST      X

~~ Paul

 

[Gazpacho]

I've left the following many times:

# Why are you reading the comments? You do know comments usually say what the code is supposed to do or what it did at one time, not what it really does now. READ THE CODE.

It's you. You are the problem.

 

[Wudang]

It's you. You are the problem.

Damn straight

 

[Unabogie]

I'm trying to remember where I read about this--Joel On Software, maybe?--anyway, a programmer who, on long projects, would place a "you are here" comment in his code whenever he took a break from coding, so that he could more easily pick up where he left off when he returned.

ETA: Presumably, unlike my own personal experiences with programming, the last function he touched didn't haunt his every waking thought (and most of his dreams) from the moment he left the code until the moment he returned.

First, I love Joel on Software. Second, I too obsess about code when I'm on a project. I'll wake up in the middle of the night and work out some scary function until I can get back to sleep. Not healthy at all.

 

[NewtonTrino]

I don't tend to obsess over specific code details but I do obsess over the top level algorithm.

 

[Paul C. Anagnostopoulos]

I overthink the data structures. Once you get them right, it's a mere matter of a function or two.

~~ Paul

 

[krelnik]

Obligatory reference to:

StackOverflow - What is the best comment in source you have ever encountered.

Hehe, yeah. Around page three of the answers on that one you'll find this response by me, which is the highest ranked answer I've ever given on Stack Overflow.

To save you a click:

Next to a local variable that had to be declared just to pass a constant to a library function:

// This only exists because Scott doesn't know how to use const correctly

 

[krelnik]

i've left the following many times:

# why are you reading the comments? You do know comments usually say what the code is supposed to do or what it did at one time, not what it really does now. Read the code.

it's you. You are the problem.

damn straight

+1000

 

[MRC_Hans]

Hehe, yeah. Around page three of the answers on that one you'll find this response by me, which is the highest ranked answer I've ever given on Stack Overflow.

To save you a click:

Actually, it may have a purpose to assign a value to a variable, instead of using a const. You see, every time a value from a const is used, it has to be converted, so if you use that value a lot of times, your code executes faster when using a variable. Been there, dunnit.

Sorry, back to topic.

Hans

 

[Paul C. Anagnostopoulos]

Actually, it may have a purpose to assign a value to a variable, instead of using a const. You see, every time a value from a const is used, it has to be converted, so if you use that value a lot of times, your code executes faster when using a variable. Been there, dunnit.

Sorry, I don't understand. What is this conversion of which you speak?

~~ Paul

 

[SkepticScott]

You see, every time a value from a const is used, it has to be converted, so if you use that value a lot of times, your code executes faster when using a variable. Been there, dunnit.

Could you give an example? Are you saying that (assuming no optimization)

int a = 1;
int b, i;

for( i = 0; i < 1000000; ++i )
  b = a;

executes faster than

const int a = 1;
int b, i;

for( i = 0; i < 1000000; ++i )
  b = a;

The compiler would generate "b=1" in the second case. In fact it would do all the conversion at compile-time, so if you had "float c = a;" that would be the same as writing "float c = (float)1;".

Most assembly languages have instructions for setting a register to an immediate value; if they're small enough they even fit in the same storage unit so the const could save a memory fetch.

 

[MRC_Hans]

Could you give an example? Are you saying that (assuming no optimization)

int a = 1;
int b, i;

for( i = 0; i < 1000000; ++i )
  b = a;

executes faster than

const int a = 1;
int b, i;

for( i = 0; i < 1000000; ++i )
  b = a;

The compiler would generate "b=1" in the second case. In fact it would do all the conversion at compile-time, so if you had "float c = a;" that would be the same as writing "float c = (float)1;".

Most assembly languages have instructions for setting a register to an immediate value; if they're small enough they even fit in the same storage unit so the const could save a memory fetch.

No, you are right about that. If you declare the const correctly, there is no difference. It will then be converted from a string '1' to int 1 at compile time.

The problem I was thinking about was if you just write b = 1;
Some programmers use DEFINE one = 1 .. which is no better than just writing '1' (but can have other uses, such as the ability to write DEFINE one = 2 )

What gives you faster performance than const is declaring them register.

Sorry, it's a long time since I have been writing code.

Hans

 

[richardm]

I've left the following many times:

# Why are you reading the comments? You do know comments usually say what the code is supposed to do or what it did at one time, not what it really does now. READ THE CODE.

Yeah, very true, however it's useful to leave helpful comments explaining what the code is supposed to be doing, so when some poor sod comes along later and has to fix it they can understand more quickly why it's wrong.

Edit: Beaten but I commented my response to explain it