The Daily WTF: Curious Perversions in Information Technology

2009-02-11 Reply Admin

Nobody:
Because they never learned why they should comment their code.
The Professor said you must comment your code so they started doing stuff like this:

i++; // increment loop variable by one

As I've made my transistion from the classroom to a real world programmer I think most problems can stem from how we were taught.

In the classroom I receive an assignment, I code it and turn it in. The only person who will ever read the source, other than me, is the Professor. The only one who will ever have to maintain it is me(and usually these are 'one-offs' which even I will never look at again).

How do you teach CS concepts like that? If no one is ever going to have to maintain it why document it? If no one besides you is ever go to touch it why worry about encapsulation, source control, etc?

What they should do is this: Have everyone code a project and turn it in. Then pass the projects back out to other people. Now everyone has to add a feature to someone else's project. Suddenly all these CS concepts become clear. You don't really comprehend why you need to document your code (and how to do it well) until you've struggled to understand somebody elses undocumented code. You don't understand the principle of orthogonality until you've had to work with someones code that has lots of unexpected dependencies etc...

I second the motion. Great idea. Unfortunately, the professors that have never had to dirty their hands with such claptrap wouldn't be able to handle it...it might sully their beautiful algorithms :)

2009-02-11 Reply Admin

Robert S. Robbins:
These comments are for the benefit of future code archeologists who may not be fluent in ancient programming languages. They will probably have nothing to go on except for a Rosetta Stone in which someone carved the same progam in COBOL, C#, and PHP.

Reminds me of the back page of an old Dr. Dobbs Journal...they did a "Hello World" program in a dozen or more different languages. Ada won for most verbose, I think, followed by COBOL. ksh (or most any scripting language) was the shortest.

2009-02-11 Reply Admin

One of the things that chaps my hide is header file comments in Linux GPL code that are nothing more than licensing notices -- why not add a couple of lines explaining what the header file is for??

2009-02-11 Reply Admin

adiener:
This isn't about personal preference, it's about software quality and ease of maintenance. Those things are objectively measurable (assuming a reasonable working definition of "quality"). Trivializing it as if it's personal preference only buries the problem deeper and perpetuates an attitude of indifference toward something with real detrimental impact. Yes, in the strictest of terms, comments have no direct effect on the quality of software after it's compiled, but their indirect effect is only one step removed from it. The philosophy of "if it does what it's supposed to when it compiles, it's good code" really isn't applicable in many situations these days.

I think it's pretty obvious from all the posts here that your idea of "objective measurability" isn't the same as everyone else's. Don't try to force your interpretation of "objective measurability" on everyone else acting like you're the absolute measure of correctness. Coding style and how one measures quality is anything but absolutely objective. I agree with nd in that nothing chaps my ass as much as someone who thinks their way is the only way of doing something and that if anybody else does it differently or has a different opinion that method is inherently wrong. I never see in the previous comment where this person said "if it does what it's supposed to when it compiles, it's good code" but that if the code accomplishes that task without compromising maintainability, extensibility, performance, etc. that's whats important and not the way that someone formats their code or that it isn't a line for line match for what you might have written. I've seen plenty of code reviews where someone will nitpick every little way of doing something because it isn't EXACTLY how that reviewer would have done it so it must not be right. That is totally unproductive and unrealistic. In my experience working for a very large enterprise those individuals that try to force everyone else to develop their way eventually hinder the productivity and innovation of others.

What I think is great about the IT industry is that it allows us to be creative and innovative with the solutions that we develop. If everyone was required to do their work exactly how everyone else does we would undoubtedly be working with the same technology and solutions as 20 or 30 years ago. Regardless, its pretty clear from the post being responded to that you don't realize that the obvious joke is on you.

So, in theme with the previous post insert reasons why someone must be wrong if they have a different opinion here: ____________

2009-02-11 Reply Admin

My first programming teacher always suggested this as a method to figure out how to write the code when not sure.

I rarely do it, but have found that it can get me past a mental block easily.

CAPTHA: wisi - Have to be wise to do this?

Claxon · 2009-02-12 Reply Admin

amischiefr:
Hell, at least it has comments. Too many f*cktards have 4k line of code classes with 0 comments. I would rather see this than none.

There is something far worse than that... It's when you get 4k lines of code with comments, BUT the only thing they comment are the most basic if statements

// if the program has commenced processing the data
if( Processing ){
    .... [ 600 lines of commentless code] ....

}else{ // if the program has not commenced processing the data
    .... [ 400 more lines of commentless code] ....
}

It makes you think "Finally! Someone who uses comments!", then crushes your soul when you realise that is the extent of their commenting prowess

Slydder · 2009-02-12 Reply Admin

Where I work (started here in Dec. 2007) there is a project called Cobaios (Site CMS for clients) that they have just recently released the 12th version of.

While searching for a bug in the system last week (I code a LOT in PHP but am a Sys Admin here not a coder) I opened a file and noticed there was not one comment in the entire file. I then egreped the entire directory tree for any PHP type comments. I found 1 comment in over 1000 files with over 500,000 lines of code. The comment that I found was stating only who originally wrote that module for the project.

I just logged out and told the developer that he would have to find the bug as I had no time for that crap.

bjolling · 2009-02-12 Reply Admin

MooseBrains:
sota:
I just realized this should probably be refactored into a method:
// write the message text WriteMessageText();

A ex-colleague would have expanded that, to make it even more supportable:

// write the message text WriteMessageText(); Log("Have written message text");

(Now imagine a class where in some methods every line looks like that)

That's nothing. An ex-colleague of mine added ellipses to everything. Imagine this every five lines:

// write the message text... WriteMessageText(); Log("Have written message text...");

[Aaaarrrghh!]

dkf · 2009-02-12 Reply Admin

Eli:
OK, smartypants, what do you suggest for a neuter singular pronoun in English? "He" is sexist and "he/she" is just awful.

I remember one online community deciding that the correct way to do it is “sh/he/it”.

I prefer “one” as that is third-person singular and refers to an individual that has a gender, but where the gender is not specified, unlike “it” where the gender is clearly neuter.

Eli:
Singular "they" is clearly going to continue to grow in usage until old farts like you accept it as valid :)

English is defined to be the language as used by English speakers. (Yes, really.) If a lot of people use “they” as a neuter singular pronoun, then that's what it is. Whatever the old farts say.

icelava · 2009-02-12 Reply Admin

See this on a daily basis.

icelava · 2009-02-12 Reply Admin

dkf:
Eli:
OK, smartypants, what do you suggest for a neuter singular pronoun in English? "He" is sexist and "he/she" is just awful.
I remember one online community deciding that the correct way to do it is “sh/he/it”.
I prefer “one” as that is third-person singular and refers to an individual that has a gender, but where the gender is not specified, unlike “it” where the gender is clearly neuter.
Eli:
Singular "they" is clearly going to continue to grow in usage until old farts like you accept it as valid :)
English is defined to be the language as used by English speakers. (Yes, really.) If a lot of people use “they” as a neuter singular pronoun, then that's what it is. Whatever the old farts say.

This is why as English users we need to create a set of words for gender-agnostic references to a person. And "one" is not it.

"When a customer sends in a feedback email, the first thing I do is write a personal repsonse to one acknowledging one's message will be read and considered in due time."

Yea. Sounds really sleek there.

2009-02-12 Reply Admin

This is my method.

Use comments as pseudo code
Code it out when ready, replacing the comments with code
Come back two days later and put in sufficient comments that help you to understand what it was you coded two days earlier and why.

...I find that two days later, if I have to think "WTF was I doing that for" and it was actually correct, I comment it.

Otherwise there's no point.

2009-02-12 Reply Admin

The debate rages on. The only thing we can agree on is that we'll never all agree.

2009-02-12 Reply Admin

As someone who also does this, I'll tell you why he does it.

When he codes something, he starts by writing out comments for the actions which must take place.

Then he writes the code to implement it.

Personally, I do that because I have to switch between 4-5 languages each day (C#, TSQL, actionscript, javascript, java, php and VB), and can't keep all of the specifics of each language in my head.

2009-02-12 Reply Admin

Ryan:
As someone who also does this, I'll tell you why he does it.
When he codes something, he starts by writing out comments for the actions which must take place.

Then he writes the code to implement it.

That's not the issue. The issue is then leaving the obsolete comments in your code. That is the WTF and that is why tihs coder sucks.

2009-02-12 Reply Admin

I have never seen TOO MANY commments but exactly the opposite, I do the same thing which pisses others off 'Why comment that'!

Example

-- Return Results return dsResults

2009-02-12 Reply Admin

Anonymous:
The debate rages on. The only thing we can agree on is that we'll never all agree.

I disagree.

pscs · 2009-02-12 Reply Admin

Ryan:
When he codes something, he starts by writing out comments for the actions which must take place.
Then he writes the code to implement it.

I used to do that, now I write function calls for the actions which must take place.

If you do it by writing comments, that's fine, but take them out afterwards. They just add clutter, and potential for mismatches between code & comments.

I rarely add comments. They're rarely necessary. Really!

In general if I do something which looks a bit odd, I'll add a comment, or if I do something, then come back a couple of months later and have to spend more than half a second to work out what was going on, I'll add a comment then.

Anyone who says you should have a comment for each 5 lines of code is just begging for stupid comments to be written. Yes, number of comments per line of code is an objective measure that can be applied to code, however it's not a very meaningful one.

//This function does something int doSomething(int x) { return (80 - x) * 50; }

has one comment per 5 lines of code, but is far less meaningful than

int calculateInsurancePremium(int age) { return (maxAge - age) * premiumCostPerYear; } which doesn't have any comments at all

A code analyser counting comments would think the first function was better than the second!

JimM · 2009-02-12 Reply Admin

icelava:
This is why as English users we need to create a set of words for gender-agnostic references to a person. And "one" is not it.
"When a customer sends in a feedback email, the first thing I do is write a personal repsonse to one acknowledging one's message will be read and considered in due time."

Yea. Sounds really sleek there.

a) Words have gender. People have sex. Seriously. Gender is a grammatical term referring to words. If you ask a person if they are male or female, you are asking them what sex they are. Just because the Victorians thought "sex" was a naughty word, doesn't mean it's the wrong one.

b) "One" is an impersonal pronoun. Using it to refer to a person you have already mentioned (i.e. "a customer" in your example) is plain wrong. You need to use a personal pronoun, like "he", "she" or "it". "They" is now usable interchangably as singular or plural, and would be the most appropriate word to be used above: the first thing I do is write a personal repsonse to them acknowledging their message.

English tends towards reductivity in it's grammar (see the dropping of thee / thou in favour of just using you), so I have no idea why you want to invent new grammar just because you can't use the existing words we have properly...

2009-02-12 Reply Admin

Well, none of you will like my code then. The following is from real, in production working code.

;[ NUMBER TO STRING ( num -- addr len )
; Takes a number off the stack and converts it to a string equivalent, with respect to the current
; number base. Number base may be between 2 and 36. The string is placed at STRBUF+1
; The length of the string (single byte) is placed at STRBUF
; This is quite a bitch of a routine. Since any number base (between 2 and 36) can
; be employed this routine is rather complex. The routine must first determine the
; appropriate powers of the number base so we can divide the target number later.
; Obviously this is expensive, so the routine remembers what the active number
; base was the last time it was called, and ONLY re-computes the exponents if the
; base has changed since the last time it was called. Sneaky.
; So, here we go, this first part computes the column values. So, if the base is
; 10, you end up with 1,10,100,1000,10000
; Oh, and, as with all our routines, we can't touch r3,r4 or r5 :-)
ntsh	data flenmh,3
		text 'NTS '
nts		data $+2
	mov *r4,r9	; get number off stack
	li r7,2	; exponent counter (base^0 and base^1 are easy to compute)
			; used as a word offset into workbuffer so counts in multiples of 2
	c @base,@lbase	; check if base has chaged since the last time we were called
	jeq dodiv	; base hasn't changed, no need to compute base powers
	mov @base,@lbase	; base has changed, store it in 'last base'
	li r0,1	; base^0 is always 1 - easy ;-)
	li r1,wrkbuf	; place to store the powers of our number base
	; determine base^x until result > 65535
	mov r0,*r1+	; store base^0 and move forward in buffer
	mov @base,*r1	; base^1 is always base ;-) store it
pwr		mov *r1+,r5	; get previous exponent
	mpy @base,r5	; multiply it by base - lower 16 bit result in r6
	mov r5,r5	; see if the result overflowed into the upper 16 bits
	jne pwrout	; there was an overflow, exit loop
	mov r6,*r1	; otherwise store result
	inct r7	; and increment exponent counter
	jmp pwr	; and repeat
	; Ok we have computed the 'column values' (powers) for our base. Now we sucessively
	; divide the number down until nothing is left, building the string equivalent as we
	; compute each digit. Just to make life harder for ourselves, we will optionally allow
	; leading zero's to be supressed. If the word at LZI>0 then leading zero's are suppressed.
pwrout	mov r7,@expcnt	; save exponent count for next time the routine is run
dodiv	mov @expcnt,r7	; entry point when exponents aren't computed. restore exponent count
	clr r8	; div instruction uses 32 bit dividend, our 16 bit argument is in r9
	clr r1	; buffer length counter
	mov @lzi,r10	; leading zero indicator (0=suppress leading zero's)
	li r0,strbuf	; address of string buffer where we will build the string.
					; first byte reserved for length
nxtdig	div @wrkbuf(r7),r8	; divide our number by exponent value. result=r8, remainder=r9
	mov r8,r8	; was the result 0?
	jeq testlz	; if yes then check if we're ignoring leading zero's
	seto r10	; not zero, so reset leading zero indicator
dodig	movb @tlut(r8),*r0+	; lookup digit value, move it to string buffer and advance buffer address
	clr r8	; clear result for next interation
	inc r1	; increment length counter
iglz	dect r7	; done all our columns/exponents?
	jne nxtdig	; loop if not
	movb @tlut(r9),*r0+	; lookup digit value, move it to string buffer and advance buffer address
	; we've done our division, push address and length to the stack and exit
	li r0,strbuf	; address of string buffer
	mov r0,*r4+	; move address to stack, increment stack pointer
	inc r1	; adjust length for remainder
	mov r1,*r4	; move length to stack
	b *r12
	; we're looking for leading zero's and ignoring them
testlz	mov r10,r10	; are we ignoring leading zero's? (0=yes)
	jne dodig	; if not then do digit normally
	jmp iglz
	; character lookup table for printing numbers between bases 2 to 36
tlut	text '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'

(Btw: The web page breaks the formatting, it's all neatly lined up, but, you get the idea about the comments)

2009-02-12 Reply Admin

I code this way normally - starting with the pseudo-code in comments. I am happy to notice that many of you do the same.

Code Dependent · 2009-02-12 Reply Admin

TMS9900:
; So, here we go, this first part computes the column values. So, if the base is ; 10, you end up with 1,10,100,1000,10000 ; Oh, and, as with all our routines, we can't touch r3,r4 or r5 :-)

Now we've gone from commenting code to having a fkn conversation with the reader. This sounds like a Surf Punks song.

"So, Jerry..." "So, Dennis..." "So!"

2009-02-12 Reply Admin

SatanClaus:
Alot of young people thing "it is obvious" what their code is doing. Sorry, you are wrong in many cases. What usually results is a furious effort to find out what variables a, i and z are doing elsewhere in the code.
This is a horrible dailyWTF as it is simply an example of what you young (sometimes arrogant) people need to learn how to do in the real world.

Because obviously you old boys never write lazy 'I'm only hanging on 'til retirement' sloppy code? Whilst we're being ageist :p

MrBester · 2009-02-12 Reply Admin

Strange that the programmer would first use (> 0 and < 8) and then use (between 1 and 7). Kind of a nitpick I guess, but it seems sloppy to me.

Because VBScript doesn't have a BETWEEN operator perhaps?

I'm surprised noone has picked up on the other obvious WTFs:

No closing of the recordset, leaving an open heavy object.
No destruction of the recordset, leaving an orphan heavy object taking up a valuable connection reference to the database. If this is Access, it will fail in short order with a semantically incorrect error description (which is a Microsoft WTF, but there you go).
Use of GetRows() on a recordset retrieved by Conn.Execute. If the goal was speed and efficiency, the recordset needs to be retrieved explicitly as a forward only, read only. And even then, as only one column of one record is required, just getting the field value would have been more efficient. And you wouldn't have to dick about with 2D arrays either.

Usage of the ? operator in the SQL would have involved the programmer to add the extra lines to create a Command object, set the connection, text and parameters (and destroy it after use of course). This would have made the function twice as long with the only benefit being a SQL injection side-stepping. As there isn't consideration for the arbitrary order in the recordset, how important is SQL injection in the mind of this programmer likely to be? And what's the betting the programmer had never used the Command object before?

2009-02-12 Reply Admin

Anon. :
Anonymous:
The debate rages on. The only thing we can agree on is that we'll never all agree.

I disagree.

I think you meant:

// disagree with commenter I disagree.

2009-02-12 Reply Admin

sota:
Anon. :
Anonymous:
The debate rages on. The only thing we can agree on is that we'll never all agree.

I disagree.

I think you meant:

// disagree with commenter I disagree.

// disagree with disagreement. I agree.

2009-02-12 Reply Admin

Sometimes I like to use comments as place=holders for unimplemented things, so in the end it ends up being an explanation of the following step... like //now we parse the image //now that we've done that, let's crunch the results


etc...
Bad practice, but I'm usually too lazy to clean em up :D

2009-02-12 Reply Admin

Guy Smiley:
I once worked at a company where we were required to add a comment for every line of code. This was an incredibly well thought out and implemented plan, especially when we had code like:
if ptr /= null then
or
for i in 1..MAX_MESSAGES loop
We ended up writing another program that would look for uncommented lines and add an appropriate comment, such as "if ptr is not equal to null" or "for 1 to MAX_MESSAGES times".

This is bullshit, and I'm not sure whether you know it. Why not put in a comment like "must have a valid customer here" or "send all messages" or similar, so to add at least a little annotation. But no... anyhow, what can you expect from people who use "ptr" as a variable name.

2009-02-12 Reply Admin

Well, as usual this is a day late, and no one will probably ever see it, however those of you who do will get a laugh.

I start every coding project that I do with a comment block apologizing for the code that I am about to write and that the reader is now looking at.

2009-02-12 Reply Admin

Often times, when I'm going through a piece of code it's because something isn't doing what it's supposed to be doing. Just as often, there is little to no commenting.

My favorite is when the coder came back and added something and left only one comment saying "Added these 50 bajillion lines to do <insert woefully undescriptive task here>", at which point I have to go through those lines and figure out what's doing what and how... and my comments usually end up looking like this.

IMO, if more commenting took this stance, people like me wouldn't spend hours looking for the piece of code that isn't working. I know what's wrong with the output, and if I knew where that portion of the code was, I could fix it quickly. But alas, nary a comment in sight.

2009-02-12 Reply Admin

Really, if this is the biggest WTF in the code, they should consider themselves lucky. Be glad there's comments at all. It just looks like the kind of thing you'd see in real production code thats been modified over the course of several years. Not every piece of code needs to be a work of art, and not every query needs to be optimized to squeeze out every ounce of performance.

Also, doing the range check the first time would bypass an SQL query. Without any additional context, the wtf-ness of this cant be determined.

Code Dependent · 2009-02-12 Reply Admin

VeryBad Man:
I start every coding project that I do with a comment block apologizing for the code that I am about to write and that the reader is now looking at.

Self-esteem issues? There's counseling for that, you know.

2009-02-12 Reply Admin

I've done exactly comments like that if I have to work with somebody's code and I'm new to the language. I don't think it's too bad of an example. I think what's worse is to comment a huge chunk of code and leave it there to do nothing.

pink_fairy · 2009-02-12 Reply Admin

Picard:
Robert S. Robbins:
These comments are for the benefit of future code archeologists who may not be fluent in ancient programming languages. They will probably have nothing to go on except for a Rosetta Stone in which someone carved the same progam in COBOL, C#, and PHP.

Reminds me of the back page of an old Dr. Dobbs Journal...they did a "Hello World" program in a dozen or more different languages. Ada won for most verbose, I think, followed by COBOL. ksh (or most any scripting language) was the shortest.

Ah, yes, but that ignores "The Evolution of a Programmer," which can be found in the Unix Hater's Handbook (amongst others). Filed under "C++"/"The COBOL of the 90s".

tbrown92030 · 2009-02-12 Reply Admin

Code Dependent:
SatanClaus:
Self documenting code is often self documenting
Ya think?
Sounds like a Beatles song: There's nothing you can do that can't be done There's nothing you can sing that can't be sung

// The following comment is true. Move to next element // The preceding comment is a lie. Move to next element ++i;

(maybe this puts the compiler into an n'th-complexity infinite binary loop :-)

pink_fairy · 2009-02-12 Reply Admin

Slydder:
Where I work (started here in Dec. 2007) there is a project called Cobaios (Site CMS for clients) that they have just recently released the 12th version of.
While searching for a bug in the system last week (I code a LOT in PHP but am a Sys Admin here not a coder) I opened a file and noticed there was not one comment in the entire file. I then egreped the entire directory tree for any PHP type comments. I found 1 comment in over 1000 files with over 500,000 lines of code. The comment that I found was stating only who originally wrote that module for the project.

I just logged out and told the developer that he would have to find the bug as I had no time for that crap.

(1) Real SysAdmins don't code in PHP. (2) 1 comment in 500 KLOC? That has to be some sort of record. It's ... it's coming to me ... it's emergent design ... no, it's plain and simple excreted waste matter, isn't it?

You have my sympathy. BTW, try Perl and a halfway decent templating engine. How you can cope with System Administration and PHP at the same time is beyond me.

pink_fairy · 2009-02-12 Reply Admin

JimM:
icelava:
This is why as English users we need to create a set of words for gender-agnostic references to a person. And "one" is not it.
"When a customer sends in a feedback email, the first thing I do is write a personal repsonse to one acknowledging one's message will be read and considered in due time."

Yea. Sounds really sleek there.
a) Words have gender. People have sex. Seriously. Gender is a grammatical term referring to words. If you ask a person if they are male or female, you are asking them what sex they are. Just because the Victorians thought "sex" was a naughty word, doesn't mean it's the wrong one.

b) "One" is an impersonal pronoun. Using it to refer to a person you have already mentioned (i.e. "a customer" in your example) is plain wrong. You need to use a personal pronoun, like "he", "she" or "it". "They" is now usable interchangably as singular or plural, and would be the most appropriate word to be used above: the first thing I do is write a personal repsonse to them acknowledging their message.

English tends towards reductivity in it's grammar (see the dropping of thee / thou in favour of just using you), so I have no idea why you want to invent new grammar just because you can't use the existing words we have properly...

Well, I agree with the reductive bit and will ignore your use of the (non-reductive) green-grocers' apostrophe. It isn't clear how to use "the existing [prepositions] we have properly," unfortunately.

Hes, shes, and (conceivably) its are likely to object to a perceived prepositional slight. Language being what it is -- not merely a means to communicate, but generally a means to inform and to persuade -- it would be nice to avoid this. "They" is good for about 95% of cases, but the other 5% involve re-casting your (or thy) original sentence such that it doesn't look halting.

I rather envy Swedish, which has only two genders: masculine, and neuter. Most nouns are masculine. The Swedes won't just forgive you if you default to masculine; they'll barely notice the transgression. And it's not as if Sweden isn't famed as a country that stands up for Wimmin, the 1980s second-wave Feminist Agenda, etc. (Partly for these reasons, it's an extremely neat place to be.)

On a reductive basis, therefore, I suggest we drop "she/her/hers." Let Scandinavia show us the way.

2009-02-12 Reply Admin

Eli:
OK, smartypants, what do you suggest for a neuter singular pronoun in English? "He" is sexist and "he/she" is just awful.
Singular "they" is clearly going to continue to grow in usage until old farts like you accept it as valid :)

Uh, how 'bout "Often, the way one learns to do something is the way ONE keeps doing it..." Keep it simple.

2009-02-12 Reply Admin

Nodody:
Which is why you should break the code up into shorter methods. Short methods are easier to read. Long methods are a code smell which should indicate to you that it is time to think about refactoring.

Nah, readability is not a great reason to break up long methods. It's much easier to scroll over 10 code blocks of 10 lines each than to figure out 10 calls to a bunch of 10-line methods somewhere else.

Break a method into smaller methods if those methods are useful to call somewhere else, are called more than once, or can be called in a different order. It's also good to do this to abstract away some data, to hide code that does a lot of housekeeping unrelated to the main purpose of the method, or to indicate that the sub-method should be decoupled for maintainability.

Mr B · 2009-02-13 Reply Admin

Tris:
Mr B:
So you weren't using version control, nor did you make a note of what was left to do when you were told to remove the TODO notes from the code?
I'd have resigned at that point too, in order to cover up my incompetence.

That's jumping to an inaccurate conclusion. I didn't say anything about source control or documentation. That doesn't mean it wasn't there....

Mr B:
I'd have resigned at that point too, in order to cover up my incompetence.

I'm sorry to hear about your incompetence.

If you had source control and documentation it wouldn't have been an issue. You raised it as an issue, so clearly you didn't have the TODO list documented (issue #1) nor did you have adequate source control (issue #2) otherwise you would have simply referred to the documentation and then rolled the code back like every other good programmer would have done. No, instead you whine about management but do nothing to change it - you'll go far!

I see what you did with the incompetence thing, that's awesome!

2009-02-13 Reply Admin

"read the natural language comments and skip over reading the actual code" Actually, as someone who started off life as amaintenance programmer, that exactly what I intend should be done with my comments and what I look for. If I'm trying to track down a bug somewhere in 3,000 lines of code spread over 10 or 20 modules I don't want to read every line of code. If I open up a module with 500 lines of code I want to see comments describing roughly what they do so I can find the starting point for the investigation.

2009-02-13 Reply Admin

There's nothing wrong with the comments in the original code fragment. If you delete everything but the comments, the algorithm is clear and may be easily ported to other languages.

I was glad to see the assembly language example with copious comments. How many of the "no comments" crowd would cower under their desks when asked to explain (or maintain) a floating point multiply or divide assembly routine which had no comments?

I have a personal requirement that my software always compiles cleanly at the end of every day. That means a lot of stubbed subroutines and functions until I get to them. They often look like (yes, FORTRAN, can you read it?): subroutine protected_div (x,y) implicit none real08 protected_div, x, y real08 tinyvalue !/1d-30/ !! TBD cc divide x by y, avoid divide by tiny value, especially 0 cc no reason to crash here c if y >= tinyvalue then c protected_div = x / y c else c protected_div = ! something else c endif return end After writing the stubbed function, there's really no reason to delete the ("CC") comments.

pscs · 2009-02-13 Reply Admin

TMS9900:
Well, none of you will like my code then. The following is from real, in production working code.

TBH, if you have to write in assembler, then you generally need lots of comments. The more expressive the language is, the fewer comments you should need.

So, Assembler is down at once end (almost totally impossible to express intent in the code itself) and OO-ish languages like C++/C# etc much nearer the other end, where most of the intent can be expressed in the language.

If you had written your code in C/C++, you'd (hopefully) have nicely structured loops, and reasonable named variables (instead of un-renamable registers) and so on, and you'd need far fewer comments.

(However, I'm surprised you'd need a function like that written in assembler, it'd generally be better written in something like C, if a C compiler is available for the platform)

2009-02-13 Reply Admin

Mr B:
If you had source control and documentation it wouldn't have been an issue. You raised it as an issue, so clearly you didn't have the TODO list documented (issue #1) nor did you have adequate source control (issue #2) otherwise you would have simply referred to the documentation and then rolled the code back like every other good programmer would have done. No, instead you whine about management but do nothing to change it - you'll go far!

The issue was that i had to put in extra work because of an arbitrary, self defeating policy decision; not that it was an actual problem.

After adding all the TODO's with with the bug / feature info, i was made to remove them. There's no excuse for that other than to really piss me off, which it did. Try tracking down where to add new features in a 1000 line page load function.....

2009-02-13 Reply Admin

Had to share. From Apache 2.2.11:

me@mybox:~/apache/conf
$ head -1 mime.types
# This is a comment. I love comments.

2009-02-13 Reply Admin

Useless comment:

// Compare n to 3
if (n>3)
...

Useful comment:

// Interface to accounting system limits us to 3 phone
// numbers per customer
if (n>3)
...

Etc.

Comments that explain the language syntax are only useful to people who don't know the language, who by definition are not capable of modifying the program any way. Thus comments like "Add a to b" are useless: I can read the code.

The one class of exceptions that I can see are when we are talking about an obscure or subtle point of language syntax. Just the other day I wrote a line of code that said "if (isReturn == transactionType.equals("R"))". The intent was that if we are presently working on a return, we only want to process records whose transation type is "R", and vice versa. But after writing that line of code, I realized that the intent might not be obvious to a reader, so I added a couple of comment lines to explain it. Sure, the code would have been easier to read if I'd said "if (isReturn==true && transationType.equals("R") || isReturn==false && !transactionType.equals("R"))". That would have done exactly the same thing but less cleanly. I preferred the obscure implementation with an explanatory comment.

2009-02-13 Reply Admin

pscs:
...
(However, I'm surprised you'd need a function like that written in assembler, it'd generally be better written in something like C, if a C compiler is available for the platform)

Could be one of...

Snippet is from legacy code, where the entire system was written in assembler,
Code was in a critical loop and had to be fast. Assembler is much faster than C, almost as fast as machine language.

2009-02-13 Reply Admin

Mark Draughn:
Nodody:
Which is why you should break the code up into shorter methods. Short methods are easier to read. Long methods are a code smell which should indicate to you that it is time to think about refactoring.
Nah, readability is not a great reason to break up long methods. It's much easier to scroll over 10 code blocks of 10 lines each than to figure out 10 calls to a bunch of 10-line methods somewhere else.
Break a method into smaller methods if those methods are useful to call somewhere else, are called more than once, or can be called in a different order. It's also good to do this to abstract away some data, to hide code that does a lot of housekeeping unrelated to the main purpose of the method, or to indicate that the sub-method should be decoupled for maintainability.

Mod this person up. These are essentially the rule of thumbs that I use.

2009-02-13 Reply Admin

pink_fairy:
Picard:
Robert S. Robbins:
These comments are for the benefit of future code archeologists who may not be fluent in ancient programming languages. They will probably have nothing to go on except for a Rosetta Stone in which someone carved the same progam in COBOL, C#, and PHP.

Reminds me of the back page of an old Dr. Dobbs Journal...they did a "Hello World" program in a dozen or more different languages. Ada won for most verbose, I think, followed by COBOL. ksh (or most any scripting language) was the shortest.
Ah, yes, but that ignores "The Evolution of a Programmer," which can be found in the Unix Hater's Handbook (amongst others). Filed under "C++"/"The COBOL of the 90s".

Thanks for the link. I forgot all about that one. Excellent examples. The absolute simplest was the dreaded Basic...which shows that sometimes the problem is a nail, and all you need is a hammer :)

2009-02-14 Reply Admin

The real WTF...WTF does it matter?

If THIS is what you find to critique in code, you need to expand your knowledge base because there are real things going on in the world that we could discuss and try to change.

I will take this ANY day over no comments, or a unary operator or something else where some script kiddie thinks he is just so darn kewl and if you are not kewl enough to want to decipher WTF he is doing, well then you just aren't kewl enough. I personally prefer to spend my time delveoping and designing, not figuring what 4 statements some genius embedded in a single method call. We coders do not do this because we don't "get it". In fact, you seem to "not get" that code is written once and read an infinate number of times. If I can put comments that describe what is going on and someone can get the point quicker, I have just been a good coder.

The coders who get together in a cube to snicker over someone's comments? Not so much.

The How, Not the Why

Leave a comment on “The How, Not the Why”