Graduating soon in Comp Sci. Need real world advice.

[Robert B.]

Pick only one:

A> 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day, but their code has
copious comments

B> 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day, but their code has
wall-to-wall unit and acceptance tests

BTW option B has also been shown to dramatically reduce the incidences of 14
hour days...

BTW, yes, I'm just starting with Java, but it's just the latest in my
arsenal. My best advice to a new programmer is to have more than one
language at which they're good. If the only tool you have in your toolbox
is a hammer, everything looks like a nail. And that advice applies to both
hardware and software.

 

[Stephen Kellett]

You say the same thing with a different spin: Comments are rarely
useful to explain what the code /does/; anyone who wants to know that
will simply read the code (and besides, the comments can easily get
out of date anyway). Comments should be used principally to explain
what the programmer meant to do, what he was thinking, and so on; this
is the kind of information that the reader can't get from the code (in
most cases).

Correct. There is no way the comment can do anything other than explain
what the programmer intended. Hopefully that will match what the codes
does. When it doesn't the next person to look at the code for a
modification/bug fix will spot the difference and fix the bug.

Stephen

 

[Stephen Kellett]

A> 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day, but their code has
copious comments

B> 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day, but their code has
wall-to-wall unit and acceptance tests

BTW option B has also been shown to dramatically reduce the incidences of 14
hour days...

I choose option C.

C> 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day, but their code has
wall-to-wall unit and acceptance tests

AND

copious documentation, comments in the source code and a version
control system.

In the case of the 2AM panic call for a bug that has got through your
acceptance and unit tests, you'd better hope there is some good
documentation and comments, as clearly your tests didn't catch the bug.

Just because your test passes the unit tests does not mean the code is
good. Passing unit tests just means the code passes what you chose to
test, nothing more. It does not mean the code is fit to ship. It *MAY*
be a good indicator that the code is fit to ship. Why can't people
understand this simple proposition?

No one was saying don't have unit tests. People (yourself included if I
understood one of your posts correctly) were saying comments and/or
documentation are not needed because unit tests remove the need for
documentation. That statement and viewpoint is incorrect.

You also need to document the unit tests to say what each test is
testing (you shouldn't have to read the unit test to find out), why you
are testing that area and for what purpose. Someone reading this at the
7AM debrief after your 2AM panic may then find out why the unit test
failed, update the test(s) and the documentation to match.

Stephen

 

[Kevin Arouza]

And, when you're outsourced, it'll make it that much easier for the
person replacing you to maintain the code as well!

LOL! In my experience these cheap H-1B Indians that they are hiring
these days have horrible coding standards.

 

[Gerry Murphy]

Think about the 2am panic call to fix a problem in someone else's code after
you've already had a hard 14 hour day and you'll not only appreciate good
comments, but you'll insist on them when you do the code walkthrus.

I've seen a lot of these in code. Things that were fixed late on a Friday
or in a rush over the weekend. One of my favorites:

if (somecondition)
do(a);
else
do(a);

 

[Gerry Murphy]

....

BTW, yes, I'm just starting with Java, but it's just the latest in my
arsenal. My best advice to a new programmer is to have more than one
language at which they're good. If the only tool you have in your toolbox
is a hammer, everything looks like a nail. And that advice applies to both
hardware and software.

Same situation with me. I remember one of my professors saying that the
most difficult computer language to learn is your second one. You have to
overcome so many unwarranted assumptions made based on the first.
I think he was right. From the third one on they do seem to get easier.

Gerry Murphy

 

[Robert B.]

I've seen a lot of these in code. Things that were fixed late on a Friday
or in a rush over the weekend. One of my favorites:

if (somecondition)
do(a);
else
do(a);

And yet there are people that will tell you that you don't need comments
because the language is "self-documenting"... What a laugh!

 

[Robert B.]

Same situation with me. I remember one of my professors saying that the
most difficult computer language to learn is your second one. You have to
overcome so many unwarranted assumptions made based on the first.
I think he was right. From the third one on they do seem to get easier.

Gerry Murphy

I think I had it fairly lucky... My first language was Assembler (which is
still my favorite!). But when you get down to it, all languages eventually
get to Assembler and, IMVHO, knowing Assembler leads me to writing tighter,
more efficient code, no matter what language I'm using. Even way back in
the dark ages, we were taught structured programming methodologies FOR
ASSEMBLER! All my early code was driver/subroutines with functionality and
data accesses isolated among different programs which isn't that far removed
from basic OOPs. Cobol, Fortran, PL/I, C, C++, Basic (from Gwhiz to VB),
and all the others... It seems that not much is really new, it's just
packaged differently. A lot of the problems that are trying to be solved
with new languages and approaches is, in fact, just a way to overcome some
really poor programmers with really poor techniques. I once had a senior
technical lead tell me that the way THEY coded was structured. It entered
at the top and exited at the bottom. What happened in between was
irrelevant! Sure, his stuff was structured, in a way, it's just that the
structure sucked! And, yes, this was another person who would argue that
their code was self-documenting...

 

[Rene]

the way THEY coded was structured. It entered at the top and exited at
the bottom. What happened in between was irrelevant! Sure, his stuff
was structured, in a way, it's just that the structure sucked! And, yes,
this was another person who would argue that their code was
self-documenting...

Code *is* self-documenting. It tells you a lot about the person/the people
who wrote it.

That might have not been intended but that can always be read out of any
code.

CU

René

 

[Ben Pfaff]

One of my favorites:

if (somecondition)
do(a);
else
do(a);

My current favorite comes from the "Nachos" software used to
teach operating system courses at several universities:

#ifdef FILESYS
halt->Execute(gInitialProgram);
#else
#ifdef SIMOS
halt->Execute(gInitialProgram);
#else
halt->Execute(gInitialProgram);
#endif
#endif // FILESYS

The programmer must have been on drugs.

 

[Mike]

I think I had it fairly lucky... My first language was Assembler (which is
still my favorite!). But when you get down to it, all languages eventually
get to Assembler and, IMVHO, knowing Assembler leads me to writing tighter,
more efficient code, no matter what language I'm using. ...

Interesting... Apart from some minor dabbling with
FORTRAN and basic, my first _serious_ language was also
assembler, but I think it has had negligable influence
on the efficiency and/or quality of my current
programming efforts.

 

[Roedy Green]

but I think it has had negligable influence
on the efficiency and/or quality of my current
programming efforts.

I spent considerable time finding the theoretically fastest ways to
code things the core of the BBL Forth compiler. Michael Abrash, the
guy who wrote many of the NT video drivers, worked with me using a
brute force optimiser that tried all possible ways of getting from A
to B.

I think that experience has given me a pretty good intuitive idea of
what code will run faster than some other. I imagine what has to
happen at the assembler level and to some extent the microcode level.
I am often quite amazed at how daft most programmers are without
assembler experience. They don't even seem to understand that file I/O
has very high overhead relative to RAM.

My knowledge of sorting was honed on a machine without any ram at all,
just a rotating magnetic drum and paper tape for input. I had lots of
time to think about why an algorithm was so slow. There is little
these days that really slaps you in the face with how inefficient some
techniques are. You have to scale way up before you notice you have a
problem.

 

[Mike]

I spent considerable time finding the theoretically fastest ways to
code things the core of the BBL Forth compiler. Michael Abrash, the
guy who wrote many of the NT video drivers, worked with me using a
brute force optimiser that tried all possible ways of getting from A
to B.

I think that experience has given me a pretty good intuitive idea of
what code will run faster than some other. I imagine what has to
happen at the assembler level and to some extent the microcode level.
I am often quite amazed at how daft most programmers are without
assembler experience. They don't even seem to understand that file I/O
has very high overhead relative to RAM.

My knowledge of sorting was honed on a machine without any ram at all,
just a rotating magnetic drum and paper tape for input. I had lots of
time to think about why an algorithm was so slow. There is little
these days that really slaps you in the face with how inefficient some
techniques are. You have to scale way up before you notice you have a
problem.

I guess we operate in somewhat different worlds. My
programming today is almost entirely in the area of
large-scale, floating point (well - large-scale for
desk-top PDs anyway) 'number-crunching'. Obviously,
choosing an apropriate algorithm for matrix-inversion,
root-extraction,or some form of interpolation is
important. But once that is done (and assuming the
machine has sufficient RAM for the problem), the speed
of the processor's floating point multiply operation
usually dominates run-time. There are not many points in
my code where 'micro-management' would provide more than
a few percent increase in speed.

Mike

 

[Robert B.]

Interesting... Apart from some minor dabbling with
FORTRAN and basic, my first _serious_ language was also
assembler, but I think it has had negligable influence
on the efficiency and/or quality of my current
programming efforts.

In 20 years of programming, at least 75% of it has been Assembler. Even
taught a few Assembler classes. The environment I was working in placed
speed of execution above all else. Plus there was a lot of bit twiddling
and so forth and the OS was fairly obscure and really preferred Assembler.
One of my instructors many years ago worked for a company that used
Assembler and either CICS or IMS. This was a guy who could read hex dump
code as fast as most people could read comic books! Anyway, with all that
Assembler experience, I found how much the expertise helped with my other
languages...

 

[Robert B.]

I spent considerable time finding the theoretically fastest ways to
code things the core of the BBL Forth compiler. Michael Abrash, the
guy who wrote many of the NT video drivers, worked with me using a
brute force optimiser that tried all possible ways of getting from A
to B.

I think that experience has given me a pretty good intuitive idea of
what code will run faster than some other. I imagine what has to
happen at the assembler level and to some extent the microcode level.
I am often quite amazed at how daft most programmers are without
assembler experience. They don't even seem to understand that file I/O
has very high overhead relative to RAM.

My knowledge of sorting was honed on a machine without any ram at all,
just a rotating magnetic drum and paper tape for input. I had lots of
time to think about why an algorithm was so slow. There is little
these days that really slaps you in the face with how inefficient some
techniques are. You have to scale way up before you notice you have a
problem.

All I have to do for an example of inefficiency is to look at MS products.
How much time is it going to take for MS to start requiring DVDs just to get
the space to contain their installation of Windows? When I went to school,
Assembler was the required first language if you were going for an IT
degree. You could go on to PCs (just making it to the scene) or stay with
mainframes - UNIX, DOS, CMS, VM. You could go to Fortran, Basic, Cobol or
others, but you had to get past Assembler first. And you were told that if
you couldn't get at least a high C in assembler, you probably weren't going
to make a very good programmer. To some extent, that was true and I think
the school was using that class to weed out the marginal students.

 

[Sudsy]

Mike wrote:

I guess we operate in somewhat different worlds. My
programming today is almost entirely in the area of
large-scale, floating point (well - large-scale for
desk-top PDs anyway) 'number-crunching'. Obviously,
choosing an apropriate algorithm for matrix-inversion,
root-extraction,or some form of interpolation is
important. But once that is done (and assuming the
machine has sufficient RAM for the problem), the speed
of the processor's floating point multiply operation
usually dominates run-time. There are not many points in
my code where 'micro-management' would provide more than
a few percent increase in speed.

Ever try Ken Iverson's APL (A Programming Language)? For
multi-dimensional matrix operations it kicks a**. Not
particularly self-documenting however. I wrote one-line
functions that even I couldn't figure out a month later!
It also uses a totally wonky character set with over-
strikes, something you could do with a 2741 terminal...

 

[Robert B.]

I guess we operate in somewhat different worlds. My
programming today is almost entirely in the area of
large-scale, floating point (well - large-scale for
desk-top PDs anyway) 'number-crunching'. Obviously,
choosing an apropriate algorithm for matrix-inversion,
root-extraction,or some form of interpolation is
important. But once that is done (and assuming the
machine has sufficient RAM for the problem), the speed
of the processor's floating point multiply operation
usually dominates run-time. There are not many points in
my code where 'micro-management' would provide more than
a few percent increase in speed.

Mike

I guess it's a matter of perspective. I've also seen that the differences
are more than a few percent. We did a test one time. The same project -
requirements, interface, database, everything was given to 2 experienced
groups. My group worked in Assembler and the other used C. The Assembler
package was 6 times faster than the C package and the C package had been
optimized. Both groups completed their assignments in the same time frame.
The C package was easier to understand for most people who weren't into
minutae, but problems were easier to find in the Assembler package because
there wasn't much between the source and the executable (no compiler
problems/eccentricities to deal with) Granted, C programmers are a lot
easier to find and the learning curve for Assembler is a LOT longer. As I
said in an earlier post - you need lots of tools in the toolbox so you know
which to use in a situation.

 

[Stephen Kellett]

Ever try Ken Iverson's APL (A Programming Language)? For
multi-dimensional matrix operations it kicks a**. Not
particularly self-documenting however. I wrote one-line
functions that even I couldn't figure out a month later!
It also uses a totally wonky character set with over-
strikes, something you could do with a 2741 terminal...

I met a chap at a Microsoft security bash the other week - he'd met the
guy that invented APL, apparently also wrote a language called A, which
is used in one bank in the world (they use 10 APL programmers to do the
equivalent work of 110 C++ programmers and have less bugs and far higher
performance). He has also written something called 'K' which is
commercially available and is incredibly fast as well - real time shares
arbitraging using K or wait overnight for the same result using C++.

Very interesting, but absolutely no use to me. I'd imagine stock
exchanges and banks would be falling over themselves for this stuff.

Stephen

 

[Stephen Kellett]

#ifdef FILESYS
halt->Execute(gInitialProgram);
#else
#ifdef SIMOS
halt->Execute(gInitialProgram);
#else
halt->Execute(gInitialProgram);
#endif
#endif // FILESYS

The programmer must have been on drugs.

Or planning ahead, realizing that some future area may require system
dependent code in this area. Putting the #ifdefs in place ahead of time
makes the next modification easier: You search for the #ifdefs and then
examine them to see if they require updating. You may even have empty
#ifdefs if you are using this strategy.

Of course you'd also want documentation and comments explaining why
you'd done this. Yet another one in the eye for the self-documenting
school of thought.

Having worked on a cross platform GIS in the early 90s (6 Unixes and
VMS) we did write code this way. Although not obvious (as witness by the
previous poster's comment) it is a useful maintenance technique.

Even better if you are able to hide the cross platform differences in
various macros in one or two header and source files.

Stephen

 

[Stephen Kellett]

Code *is* self-documenting.

Code documents what the code does. That isn't much use - you need to
know what the code is meant to do - that is what comments and
documentation are for. Which is why "code is self documenting" is very
poor software engineering attitude to take - it shows you don't
understand a fundamental insight about writing and maintaining reliable
code.

It tells you a lot about the person/the people
who wrote it.

And nothing about the intended effect of the code, only the actual
effect of the code.

People teaching comp sci. are obviously not teaching something simple
but fundamental when we keep seeing this nonsense about code being self
documenting. Sigh.

Stephen