For programmers...

[JeffDG]

Always remember to document your code!

 

[LDJones]

Coding fun!

 

[silver-eagle]

Verbose (off)
.
"If you understand [the language], why do you need documentation?"
.
And the worst job I ever had programming was doing maintenance. This as especially true on a program converted from Honeywell COBOL to IBM COBOL by a automated tool.

 

[MAKG1]

#define like {
#define man ;}
#define an ;
#define SayBro /*
#define CheckItOut */


SayBro like, this is some rad ****, so CheckItOut

like
    a = b
         an
    c = d
man

SayBro , like who needs help from them compiler choads anyway?
THIS is the way to write CLEAR code.  I mean really!  CheckItOut

like SayBro this is ShellSort straight out of the white book, but in
a readable form.

CheckItOut man

#define YoDude for(
#define OK     )
#define is     =
#define AND    &&
#define as
#define Do
#define long
#define some
#define make
#define ****
#define FAROUT

shell(v, n) SayBro sort v[0]...v[n-1] into increasing order CheckItOut
int v[], n;

like int gap, i, j, temp;

YoDude gap is n/2 an as long as gap > 0 Do some **** an make gap /=2 OK
    YoDude i is gap an as long as i < n Do some **** an make i++ OK
        YoDude j is i - gap an as long as j >= 0 AND v[j] > v[j+gap] Do some
            **** an make j -= gap OK
            like
                temp is v[j]      an
                v[j] is v[j+gap]  an
                v[j+gap] is temp
            man
FAROUT man

SayBro like, B there OB square!  CheckItOut

 

[flyingron]

Every time I find a really stupid or incorrectly implemented piece of code I mark it with an explanation of the problem with the word BOGUS added. The number of O's is a good indicator of how bad the code was.

Example:

/*
* BOOOOOOOOOOOOOOGUS
*
* This code says it averages the bearing angles but you don't average angles by adding
* them up and dividing by n. Also there's a fence post error that skips the last angle in the
* set.
*/

 

[SixPapaCharlie]

I document my code because I know when I look at it 3 years later, I am going to be scared of it.

 

[Matthew]

I had the joy of maintaining legacy code on several products.

One had a single comment in the whose project that said: "Harry's wife had a baby"

Another had only one comment that said simply: "hypotenuse"

 

[RBeaubien]

As a programmer, the only commenting I put in my code is to describe something that isn't clear in the code. Usually only to say WHY I am doing something. This typically ends up being a lot more useful when returning to it later. Written correctly, with proper coding standards, code is typically self-documenting.

 

[C182P]

I work with someone who insists his code doesn't need documentation because it's "self documenting". The same guy, a CS PhD, says he won't try to explain his code to other developers because they won't be able to understand it.

How he still has a job, I don't know, but I have strong suspicions it involves photographs depicting certain humans and random farm animals in acts one doesn't normally ever see in a lifetime.

 

[Matthew]

I've heard "self documenting" plenty of times, and it's true, to an extent. It can help explain what's being done, but not why.

 

[RBeaubien]

The key part of that is "proper coding standards". Variable naming standards, code layout, refactoring, etc. all lead to self-documenting code. If you don't name your variables, methods, etc. in a fashion that tells you what it is, you will not have self-documenting code.

 

[SixPapaCharlie]

There is nothing wrong with taking the extra step and adding comments.
My company has lots of developers and not all are seasoned.

I ask that my programmers add comments so the junior developers can understand whats going and because 15 years from now when standards have changed 20 times, it is there for reference.

We have a lot of legacy code that was probably "Self documenting" to the programmer that wrote it in the 90s. However, it is multi-threaded stuff and a nightmare to modify.

There is no good reason to not add some comments. If you are in that big of a hurry you are going to be revisiting it again anyway.

 

[murphey]

I document my code because I know when I look at it 3 years later, I am going to be scared of it.

+1000

 

[jhausch]

Quick comment about comments...
"I can read your code, but I can't read your mind"

I always took that to mean a quick description of "why" is more effective than a comment that repeats the "what" of the code that follows..

 

[MAKG1]

Variable naming standards, code layout, refactoring, etc. all lead to self-documenting code.

You forgot "trivial algorithms."

I doubt too many coders could tell the difference between a shellsort and insertion sort by sight.

And a LOT will not understand the following:

double discr = B*B-4*A*C;
double x1 = (-B+sqrt(discr)) / 2 / A;
double x2 = (-B-sqrt(discr)) / 2 / A;

Comments should also explain when you can get NaN, why one solution is chosen over another, and so on.

I include references to ICDs and other design documents when it isn't obvious or trivial.

 

[MAKG1]

However, it is multi-threaded stuff and a nightmare to modify.

No kidding. There is a lot of really bad multithreaded code out there, and rush-to-code makes that in particular very expensive to debug.

There are only a few instances where multithreaded code is actually required (and then, it really needs to be designed or it will be ineffective), and single-threaded reactive patterns are almost always faster than ad-hoc complex multithreaded crap, and orders of magnitude cheaper to maintain.

I've seen subcontractors reacting to a mutex-driven bottleneck by adding more threads.

 

[flyingron]

Many years ago while preparing a follow-on to a previous government contract, someone got the great idea that we should count lines of code to use in the proposal. So we set out to write a program to do the counting. It listed (for the benefit of whoever wanted these stats) the number of lines in each module's files both total, number of non-whitespace lines, and number of comment lines. We found one module that was particularly odd...

Tom: Jerry, the code counter says the database module only has one comment in it.
Jerry: There's something wrong with the program.
Tom: Why do you think that?
Jerry: Because there aren't any comments in it.

Sure enough he was right. We had counted the .TITLE or some similar directive in an assembly module as being a comment.

 

[flyingron]

I had one guy who fortunately quit while I was on the way in to firing him. Years later I found we were leaking memory in a module that nobody had touched in 15 years. This was odd so I pulled out the source code history and found that this clown and deleted the free() function in it. (I knew what happened, if you corrupt the memory arena, one place it often blows up as a result is when deallocating memory, so this guy had his code blow up on this free() statement so he "fixed" it by deleting it).

The thing that bites me is putting diagnostic messages in that aren't descriptive enough. I had a guy using one of my early internet routers I wrote. He called me and the conversation went like this:

USER: The router is printing errors.
ME: OK, what kind of errors.
USER: Something about the ethernet driver.
ME: OK, is it printing the CSR register or something.
USER: Umm...no...um.mm... it's something about trailers
ME: (thinking a bit)...Oh, is it "TRAILERS MAKE ME BARF" by any chance.
USER: Yes that's it.

The other one was when one of our programmers was porting our code to a Cray. Now we had always endeavored to make our stuff as portable as possible and it ran on just about everything out there but the Cray's architecture (24 bit pointers, 64 bit words with no partial words, not even real characters support) taxed those limits. Deep down in the code there was a consistency check and when it couldn't figure out how to adapt it printed:

"You've got to be kidding."

I got a call from my coworker and said "That sounds like one of yours."

 

[JeffDG]

You forgot "trivial algorithms."

I doubt too many coders could tell the difference between a shellsort and insertion sort by sight.

And a LOT will not understand the following:

double discr = B*B-4*A*C;
double x1 = (-B+sqrt(discr)) / 2 / A;
double x2 = (-B-sqrt(discr)) / 2 / A;

Comments should also explain when you can get NaN, why one solution is chosen over another, and so on.

I include references to ICDs and other design documents when it isn't obvious or trivial.

You really should catch for rootless quadratic equations.

 

[Capt. Geoffrey Thorpe]

Quick comment about comments...
"I can read your code, but I can't read your mind"

I always took that to mean a quick description of "why" is more effective than a comment that repeats the "what" of the code that follows..

I recall some assembly code that had a comment on every line that explained exactly what that line did. For example, (and I'm making this up) shl bx,1 would be followed by the comment: shift register bx left 1. Of course, there were no other comments explaining why one would be shifting bx or what was stored in it or anything else

Then, there was the time a guy came by with a chunk of code and asked if I could look at it. After about 10 minutes, I finally said "This makes no sense whatsoever - who was the idiot that wrote it?" He replied "You wrote it, that's why I'm asking you about it."

And there was the lady that was very particular about lining up all of the comment deliminators and other odds and ends. We would ship functioning code over to her (I was research, she was production) and all of a sudden, it wouldn't work. "What changed?" "Nothing, I just did some clean up." A file compare would reveal that 90% of the lines had changes so trying to sort out the functional changes from the formatting changes... Anyhow, I decided I was not going to get burned by this on one big project. I studied her spacing and formatting so I would get it exactly right. And, I even went one step further - every comment had a * at the end of each line exactly lined up from top to bottom, but the end of her text was ragged. I went through adding extra spaces to align the right margin of the text so it would be perfect. Nothing for her to improve on. Shipped the code over, waited, then did a compare to see what happened. She had moved all the extra spaces to make the text margin ragged but kept the *'s in a line.

And, yes, I worked with those who felt the code was "self documenting".

And the person who impressed management by writing the "How to write quality code" manual. 50 or so pages to document where every space, return, comment, comma, etc. was to be placed to make the format exactly right. Something for management to hold up as an example for us to follow. But nowhere in that document was there one single word about requirements or anything about code functionality. Which pretty much matched how this persons code was written. Formatted well, but full of bugs and omissions. End result? A promotion for this person.

 

[denverpilot]

#define like {

#define man ;}

#define an ;

#define SayBro /*

#define CheckItOut */





SayBro like, this is some rad ****, so CheckItOut



like

    a = b

         an

    c = d

man



SayBro , like who needs help from them compiler choads anyway?

THIS is the way to write CLEAR code.  I mean really!  CheckItOut



like SayBro this is ShellSort straight out of the white book, but in

a readable form.



CheckItOut man



#define YoDude for(

#define OK     )

#define is     =

#define AND    &&

#define as

#define Do

#define long

#define some

#define make

#define ****

#define FAROUT



shell(v, n) SayBro sort v[0]...v[n-1] into increasing order CheckItOut

int v[], n;



like int gap, i, j, temp;



YoDude gap is n/2 an as long as gap > 0 Do some **** an make gap /=2 OK

    YoDude i is gap an as long as i < n Do some **** an make i++ OK

        YoDude j is i - gap an as long as j >= 0 AND v[j] > v[j+gap] Do some

            **** an make j -= gap OK

            like

                temp is v[j]      an

                v[j] is v[j+gap]  an

                v[j+gap] is temp

            man

FAROUT man



SayBro like, B there OB square!  CheckItOut

Structured code without object orientation. The kids don't do that anymore.

 

[denverpilot]

Every time I find a really stupid or incorrectly implemented piece of code I mark it with an explanation of the problem with the word BOGUS added. The number of O's is a good indicator of how bad the code was.



Example:



/*

* BOOOOOOOOOOOOOOGUS

*

* This code says it averages the bearing angles but you don't average angles by adding

* them up and dividing by n. Also there's a fence post error that skips the last angle in the

* set.

*/

Waste of time. Just fix it.

 

[Capt. Geoffrey Thorpe]

"Optimized" code.

Management decided that the self diagnostic portion of the code was "too big". How in the world that determination was made is beyond me, but something had to be done. So, they assigned three people to figure out how to reduce the space required. They notice that for nearly every sensor input, the first step in the diagnostic was to compare it to short / open circuit limits and then "values not found on the face of the earth" limits. So, one of (many) changes was a routine that required you to put the four limit values in memory in the correct order and use function to do all the compares without actually addressing each of the individual values - you just made a call with the name of the first parameter. Saved hundreds of bytes. The only problem was when you wanted to make a change to the self diagnostic code and the code went to someone who was not "in" on the changes, the change request would come back with the note on the order of "This code can't be changed because it doesn't exist." It usually took an hour or so to show them that the code really did exist, how it could be found, and that it really did work...

That code was really fun.

 

[flyingron]

Waste of time. Just fix it.

I usually fix it, but sometimes I have to figure out what it was doing before and explain why my fix is an improvement.

 

[MAKG1]

You really should catch for rootless quadratic equations.

Of course. Or prove they are impossible, in the comments. Or handle the complex roots.

I didn't give you a whole routine. Those 2-3 lines are enough to trigger the bug eyes; there is no need to make a functional method to do that.

 

[MAKG1]

Structured code without object orientation. The kids don't do that anymore.

Would it make you happier if I wrapped it in

class BS {
public:
...
}

?

FYI, critical real-time systems are still written in C sometimes, as object orientation can hide performance bottlenecks.

 

[JeffDG]

Of course. Or prove they are impossible, in the comments. Or handle the complex roots.

I didn't give you a whole routine. Those 2-3 lines are enough to trigger the bug eyes; there is no need to make a functional method to do that.

Yeah, and I could just make a smart-ass comment showing I understood what your code was doing and be an ******* at the same time!

 

[denverpilot]

Would it make you happier if I wrapped it in



class BS {

public:

...

}



?



FYI, critical real-time systems are still written in C sometimes, as object orientation can hide performance bottlenecks.

I don't care. I learned ASM and structured and think the concept of sending messages to black box objects is retarded.

 

[SixPapaCharlie]

we're nerds.

 

[MAKG1]

we're nerds.

No more so than the various crowds I hang with.

At the last CAP meeting, we had the cadets making model gliders out of paper plates, cups, and popsicle sticks. One of the senior members made a pretty good Enterprise (NCC 1701A). Didn't glide very well, though.

The kids are too young to know even who Seven of Nine was, but the seniors all got a laugh.

 

[denverpilot]

We've regulated and overpriced all the fun stuff in the name of safety. There's plenty of us who'd rather shoot bottle rockets at each other than make paper airplanes. Not approved behavior anymore. Heck, most of us would rather do most of the stuff on Mythbusters than watch those two twits do it. But at least they figured out how... Get a video camera and call it a TV show.

 

[RogerT]

I document my code because I know when I look at it 3 years later, I am going to be scared of it.

Bingo. I documented stuff so that several years later I could figure out
what the heck I was thinking.

RT

 

[dmspilot]

The kids are too young to know even who Seven of Nine was, but the seniors all got a laugh.

"Seven of mine! Assimilate me!!"

 

[MAKG1]

We've regulated and overpriced all the fun stuff in the name of safety. There's plenty of us who'd rather shoot bottle rockets at each other than make paper airplanes. Not approved behavior anymore. Heck, most of us would rather do most of the stuff on Mythbusters than watch those two twits do it. But at least they figured out how... Get a video camera and call it a TV show.

If you had ever seen them in action, you would know they are a lot more than two (or five) guys and a camera or two. They do quite a bit of analysis before blowing stuff up.

Had they not, someone would be dead. Much of the stuff they play with is well beyond toys.

We see them at work once a year or so, folding paper with a forklift or kicking helium filled footballs. There haven't been explosives at NUQ for 20 years, so they go elsewhere for that (I think it's R-2531).

 

[poadeleted21]

If you had ever seen them in action, you would know they are a lot more than two (or five) guys and a camera or two. They do quite a bit of analysis before blowing stuff up.

Had they not, someone would be dead. Much of the stuff they play with is well beyond toys.

We see them at work once a year or so, folding paper with a forklift or kicking helium filled footballs.

We used to fill anvils and pipes with acetylene. The best was when a guy filled a 55 gallon trash bag full tied it up, then lit a shop rag and "hockey pucked" it over to the trash bag BOOOOMMMM!!!!. We lived.

 

[murphey]

You forgot "trivial algorithms."

I doubt too many coders could tell the difference between a shellsort and insertion sort by sight.

And a LOT will not understand the following:

double discr = B*B-4*A*C;
double x1 = (-B+sqrt(discr)) / 2 / A;
double x2 = (-B-sqrt(discr)) / 2 / A;

Comments should also explain when you can get NaN, why one solution is chosen over another, and so on.

I include references to ICDs and other design documents when it isn't obvious or trivial.

Shell v. insertion - yes, I can tell the difference by inspection.

As for why the quad equation up there can get NaN, because if A is zero, that means it's not a quad but a linear equation so there can't be any imaginary roots.

tsk tsk tsk

 

[MAKG1]

We used to fill anvils and pipes with acetylene. The best was when a guy filled a 55 gallon trash bag full tied it up, then lit a shop rag and "hockey pucked" it over to the trash bag BOOOOMMMM!!!!. We lived.

Yup, you did something stupid and lived. Therefore, no one else dies from stupidity, even with actual detonations. Gotcha.

 

[murphey]

No more so than the various crowds I hang with.

At the last CAP meeting, we had the cadets making model gliders out of paper plates, cups, and popsicle sticks. One of the senior members made a pretty good Enterprise (NCC 1701A). Didn't glide very well, though.

The kids are too young to know even who Seven of Nine was, but the seniors all got a laugh.

Or as she was known, 8:53

 

[MAKG1]

Shell v. insertion - yes, I can tell the difference by inspection.

As for why the quad equation up there can get NaN, because if A is zero, that means it's not a quad but a linear equation so there can't be any imaginary roots.

tsk tsk tsk

That's not all of them. Discr can be negative.

These are doubles, not complex's.

And those are the real roots. You can only have pure imaginary roots if B is zero and A and C have the same sign.

 

[silver-eagle]

I have fragments of code all over the place, wrapped up and imitating real code that works. I've been known to take out whole systems trying out my little fragments. One of these days, I'll write intelligent comments that I can actually interpret 3 years later.
It would also help if I respected the end of a table, and I don't mean the kitchen table either.