What Compsci textbooks don't tell you: Real world code sucks There’s a kind of cognitive dissonance in most people who’ve moved from the academic study of computer science to a job as a real-world software developer. The conflict lies in the fact that, whereas nearly every sample program in every textbook is a perfect and well-thought-out specimen, virtually no software out in the wild is …
...- if it is less than 20 lines, it's probably too small, more than 60 definitely too big...
And this assumes no compiler bugs.
20 years ago, I managed to write a program that crashed the Pascal compiler on a dual DPS-90 running CP-6. The functions were so short that they could be compiled into object code faster than the compiler's internal object-naming routine could generate internal names. This caused two functions to have the same name, which would cause the linker to crash.
@Mark Honman
I agree with 90% of what you wrote but you lost me at the less than 20 lines bit.
1 short functions can be great for things you have to do 50 times and as stated previously the compiler can just inline to improve efficiency.
2. In C they are great for forcing type safety around generic libraries that lose type safety. A good example of this is the function pointers in one of the products in our office. The code has certain options depending on where the calls happen in the protocol so short wrappers can be used to ensure that only the correct functions are added to the list of options. (before anyone brings this up. The items also depend on what modules are loaded so switch() wouldn't even work.)
@Gerhard
The 20 lines bit comes from the terminals of old - that's how much you can see at one go (60 lines on a printout page).
I've got to agree with the "wrapper" type of function, hat you've described. I guess my opinion comes from having done a lot of maintenance, and the frustration of following the flow of control in OO code that passes from one inconsequential little method to another. is a maze of twisty little methods, all alike.
On the other hand there were some shockers in the old days, 1000-line Fortran IV routines (don't get me started on common blocks) , and a supervisor who having discovered the Pascal CASE statement considered that it made IF... THEN.. ELSE obsolete.
OO shockers seem to be small, e.g. a simple "pure" function (no state, global references or side effects) that was implemented as a method, and the caller of this 8-line function was expected to instantiate an object of this class, call the method, and then throw the object away.
In fact there's a pattern here... it's so easy when one has discovered something new (COMMON blocks, CASE statements, object-orientation) to unthinkingly use this new shiny (or orgnisatoinally mandated tool/method) to solve every imaginable problem including those that can be more effectively solved the old-fashioned way.
As another commenter said, that is a common factor in poor-quality code.
Agree with that except that we write some performance critical code which can look very abstract - almost every line of code is commented because efficient code is not always as readable as one might like - but again, the the comment represents the logic - what we are seeking to achieve with the following line - and the code the implementation
You obviously never write code that implements standards or interacts with the outside world.
Of course it shouldn't be necessary to write a comment to explain what a line of code is going to do, but I often find it necessary to write comments explaining why it is doing it. I may need to refer to a standards document or another source that I used when writing the code. Sometimes it's one sentence in an entire standard or reference manual that's important - what should I do, hope the future me remembers or that someone else is psychic enough to find that reference?
Identifiers should be succinct andNotTediouselyLongWinded. Presumably you are using a language with namespaces and so the enclosing namespace brings contect that need not be repeated in a choice of variable name.
On comments, I too hate _bad_ comments. Learn how to write good comments because sometimes they are necessary - for example, after you have got a good implementation that gives the right result, you may need to alter it for, for example, speed or memory optimizations. These optimizations may not allow the luxury of being in their own function and are going to be obtuse.
I always thought K & R got it about right. Then some illiterate foreigner working for Microsoft thought it a good idea to spatter capital letters in the middle of identifiers.
Some people were upset when I ran code reviews and asked for a compiler listing of the source, which would include name tables etc. So you could see what were integers, what were procedures, etc; and whether some of them were keyboarding errors. And indeed, whether it actually compiled. Call me cynical, but I had to deal with contractors.
> Include some comments!
That deserves a reply of its own. I hate comments.
There are certainly hateful comments ... but comments are a valuable tool when used correctly. Comments deserve to be loved, but not indiscriminately!
Even if they start out accurate they get out of date because there's nothing to enforce change in them as the code changes.
That's a problem one needs to be aware of ... but is easily sorted by code reviews. The fact that the code has changed but the comment hasn't is easily seen from version diffs, if you look for it.
Far better. Far better is to write code that is self documenting.
I agree with that absolutely, and most of the time you're right that it isn't difficult ... but sometimes there is information about a piece of code that isn't easily conveyed by careful structure and naming, and then comments are invaluable.
The interface definition should say what a piece of code does.
The code itself says how it does it -- but comments may also be needed for clarity.
Only comments can say why it does it!
Big brother because he's the ultimate code reviewer, and we need him too!
> Big brother because he's the ultimate code reviewer, and we need him too!
Not according to Charles Stross. From "Big Brother Iron":
I am a systems manager in the abstract realm of the Computer, the great Party-designed, transistorised, thinking machine that lurks in a bomb-proofed bunker in Docklands. It’s my job to keep the behemoth running: to this end I have wheel authority, access all areas. The year is probably 2018, old calendar, but nobody’s very sure about it any more—too many transcription errors crept in during the 1980’s, back when not even MiniLove was preserving truly accurate records. It’s probably safest just to say that officially this is the Year 99, the pre-centenary of our beloved Big Brother’s birth.
It’s been the Year 99 for thirty-three months now, and I’m not sure how much longer we can keep it that way without someone in the Directorate noticing. I’m one of the OverStaffCommanders on the year 100 project; it’s my job to help stop various types of chaos breaking out when the clocks roll round and we need to use an extra digit to store dates entered since the birth of our Leader and Teacher.
Mine is a job which should never have been needed. Unfortunately when the Party infobosses designed the Computer they specified a command language which is a strict semantic subset of core Newspeak—politically meaningless statements will be rejected by the translators that convert them into low-level machinethink commands. This was a nice idea in the cloistered offices of the party theoreticians, but a fat lot of use in the real world—for those of us with real work to do. I mean, if you can’t talk about stock shrinkage and embezzlement how can you balance your central planning books? Even the private ones you don’t drag up in public? It didn’t take long for various people to add a heap of extremely dubious undocumented machinethink archives in order to get things done. And now we’re stuck policing the resulting mess to make sure it doesn’t thoughtsmash because of an errant digit.
That isn’t the worst of it. The Party by definition cannot be wrong. But the party, in all its glorious wisdom announced in 1997 that the supervisor program used by all their Class D computers was Correct. (That was not long after the Mathematicians Purge.) Bugs do not exist in a Correct system; therefore anyone who discovers one is an enemy of the party and must be remotivated. So nothing can be wrong with the Computer, even if those of us who know such things are aware that in about three months from now half the novel writers and voice typers in Oceania will start churning out nonsense.
I hate comments. Even if they start out accurate they get out of date because there's nothing to enforce change in them as the code changes.
In other words, you can't be arsed to update a comment or three after you poke at the code? Sounds like basic laziness (if not intermediate to advanced laziness) to me. Besides, I'd have thought you'd want to brag about the wonderfulness of the code/patch/refactoring you just wrote, and why the mechanism you used in doing that was so much superior to that which your opus replaced. Think of it that way, and it's not a comment, its an advertisement!
In other words, you can't be arsed to update a comment or three after you poke at the code?
No. It's better to break down code blocks into short functions (aka methods) and to use meaningful, explanatory names for these methods. Then your code is self-documenting and there's no possibility of comments becoming detached from code, or worse, comments mis-describing code. The main problem with this technique is a tendency for the less wise to economise by writing short method names, or to think that, just because they have a long method name, the code must be self-documenting. Public API code still needs documenting.
Don't miss out on
Anyone not using them (along with switching on all the compile time code analysis your IDE offers and letting Sonar run on the source every fracking day) should be looking at a pink slip presto.
Yeah, this last statement about including some comments stopped me cold. The author lost credibility here. Generally, the only time when comments are needed is to document the "why" of something that isn't obvious. There are a few exceptions, but before you write a comment, try really hard to name your variables or methods better, or do some other refactoring to make the code itself say what it does. Comments are almost always incorrect and therefore misleading. Drop all the javadoc, and delete all comments in the code whenever you see them, unless they are actually explaining a "why".
Self documenting code is fine, there is real no point using comments to state the totally obvious - but after many years of getting commenting wrong and (rightly) believing my efforts to be a waste of time for the reasons you state, I now firmly believe that a short comment above the method signature along the lines of: "the purpose of this block is to arrive at the optimum alpha value for [some specific thing]" - rather than stating something like "add param a to param b and take away the remaining value times some magic number declared const somewhere", which anyone reading the code can see for themselves.
That way you can see what the method is actually FOR which can be rather helpful if it turns out to be doing things wrong - while the wrongness can be addressed by first reading the code then stepping through it.
It's really the classic O-O separation of business logic from implementation detail. If you can't get that right your program's components *will be hard to refactor and very hard if not impossible to re-use.
The real world doesn't have the luxury of picking discrete problems and dedicating 2 or 3 years to solving them. It has to be pragmatic and sometimes pragmatism means shipping something which does the job even if it is imperfect by some arbitrary criteria.
It has to deal with problems which are complex, it is often feature driven, it is developed over time, it is affected by issues such as security, performance, incremental development, long term support, delivery dates, budgets, manpower shortages. Code might be worked on by multiple hands in waves as people come and go from the project.
And sometimes that means bad code. Who is surprised by that?
With clear and sensible interfaces.
Part of the difficulty in getting this done is that requirements are barely ever exhaustive and are very subject to change (though once I got handed a multi-thousand page standard and got told 'implement this!). The other problem is other people - your definition and mine may differ significantly here.
I do wonder though as you draw a lot of your anecdata from the world of finance - Most of the best engineers I've met in a 12 year career (so far) wouldn't touch the city, and not just because they didn't like getting out of bed in the morning - do you think that this sector in particular suffers from big egos matched with decidedly average aptitude?
Also have to agree with the general theme - real world software problems are messy and don't often occupy the idealised domain that academics often tackle.
Self reply to clarify (and keep wittering 'cos the alternative is hacking at some terrible code).
When I say "Your definition and mine may differ" I mean our respective definitions of clear and sensible.
For instance I've worked in places where the ternary operator in C was not allowed in case it confused some (experience<1?"junior":"incompetent") developers. Whereas I find a quick ternary in the right place to be easier to comprehend than padding the code out with more standard if/else lines. And this is a trivial example, when it comes to structuring large volumes of code there are so many different approaches that can be taken, and so many ways to get it wrong, that you really often end up with something that seems to have grown organically rather than really been designed.
This. Which is why I doc the living hell out of my code so that people reading it (or the API) know what I mean by "foo" and how I expect it to behave. If they contact me to ask a question, either they haven't read the docs (in which case I give them short shrift for wasting my time*) or the docs were inadequate (in which case I update them).
And if coders don't understand a ternary operator, you need better coders.
*That may seem a bit harsh, and I don't actually mind answering sensible questions. But it's not a case of just one person asking, it's the next and the next and the next and the...so I make them read the docs and come back with a sensible answer. I know some folks always do check the docs, so I know from the get-go they are asking something sensible. Other folks? Not so much.
This post has been deleted by its author
OK, I need to get to my 100th downvote, so it might as well be now.
I've been doing this for longer that a good number of you broomtails, based on the comments I've read here. And I daresay that I've been using (and fixing code from abusing) the ternary operator in C and C++ for longer that some of you may have been alive. (Yeah, yeah, I know, "Shut up, ol' man!" Please, hear me out....) Given that, I am quite capable of "understanding the ternary operator". And I've also come to understand that, in the hands of some less-than-talented, or less-than-disciplined practitioners, the ternary operator can be made to resemble that snippet of APL code in the original article. Like most things in C/C++, this is a double-edged sword; it can be an immense help (indeed, the alternative to ternary operators in a C macro would cause the hair on the neck of the most steely programmers to stand on end). And nesting them can turn the most elegant code into a WSH (Warm, Steaming Heap).
I don't wish to comment on the wisdom of banning a ternary operator from use, but I will say that a shop that has such a ban probably has it due to long term and rampant abuse by cowboys who "understand the ternary operator".
No, they had the ban because they were less than competent. It was one of several arcane rules and was matched with a vcs cobbled together from glue, string and fear of progress.
I've been doing this for a dozen years now too, perhaps not as long as you, but I've come to recognise that there are a lot of very mediocre dev shops out there. I'm not a 'rockstar' but I am half decent at what I do and they were not. I've seen worse since...
We shouldn't be employing cowboys to write code, unless we want to drive our businesses to a slaughter factory.
Seriously folks. Try to put recruitment into the hands of people who know what they're doing; then there's a chance they'll be able to write good code rather than garbage.
C consists far too much of punctuation anyway, and I assume that the formula in words is logically identical - but, hey, what you do is fine with a meaningful comment.
But when we write Java (although I personally don't), our unit policy is to ban a particular Java keyword, apparently at random but presumably because one of the senior programmers or managers read an article online that said it's inefficient or confusing, or it doesn't exist in their favourite language or their college programming course. I think it's "break", although it could be "for".
We have no policy on comments but a belief that since humans are smarter than computers (I suppose), it is perfectly obvious what a program does anyway. Apparently we also assume that that is always the same as what it was supposed to do.
I work with Microsoft Transact-SQL 2005 and I write stored procedures in which database and object references in dynamic SQL are elegantly tokenized as fully qualified terms, and then I realised that I myself can't read that afterwards, so now I include comments that in -this- batch, each appearance of token @[output} is REPLACEd with [NS_01].[dbo].[StaffAbsence_2010] or whichever namespace number and year number are appropriate to the occasion.
This post has been deleted by its author
Oh,and someone in our organisation doesn't know or doesn't want to know that a CASE statement can have more than two parts. Which is the damn point of it. We get "CASE WHEN i = 1 THEN 'one' ELSE CASE WHEN i = 2 THEN 'two' ELSE CASE WHEN i = 3 THEN 'three' END END END". (But with line breaks at least.) I haven't caught them yet. Which exposes another mistake that we make, nobody's name is on most of this junk.
I work for Anonymous Organisation, which they aren't going to admit. Maybe I work for you.
I've worked on several medical coding projects where, after analyzing the comment free code, it was obvious that the programmer had never really understood HOW the project was supposed to work ... my guess is that he wanted to get the job done, get paid and get out of there (which he did).
I do agree with AndrueC - bad comments are far worse that no comments at all and too many programers simply don't have the understanding of the project to write constructive comments.
...but then decays.
"I'll just shim this minor edge case in here...it's easier than re-architecting a bunch of classes" [repeat a few hundred times]
"Oh crap, this condition was never envisaged...I'll hard code in an if-else block to cope." [repeat a few hundred times]
"I really should update the docs, but there's no documentation time in the schedule, and I have 100 tasks to do before the end of the week."
"Unity test? Yeah, I should, but there's no time in the schedule."
"This code is obvious, I don't need comments."
"Code review? No time, no time...everyone is too busy."
"Hmm...fixing this minor UI glitch properly is going to mean re-writing loads of code to provide proper abstraction...the manager won't believe me that such a small change on the UI will take two weeks...better hack it than get into an argument." [repeat a few hundred times]
[Two years pass]
"HOLY JAYSUZ! What is this shit? What does that mean? WTF is that branch meant to be doing? Oh dear gawd! Who wrote this piece of shit? Oh, wait....oops"
You need to allow 3 to 5 times the coding duration if you expect to get quality.
See this is why I use two identities at work.
When strolling around the office, attending meetings and performing tidy software fixes everyone knows me as George, but at the desk I can become Ian Sanderson Jr at anytime I need to make a hack fix.
Who is Ian Sanderson Jr? He is an enigma, no-one has ever seen him but you might occasionally see a commit notice bearing his name. His address in outlook says he works from home out of a remote rural location far from any company office. He rarely responds to emails and his phone number isn't listed.
People rarely bother Ian Sanderson Jr about his hack fixes.
They write quite a bit of it themselves!
Not all the code they see is in books. A lot of it is ill-documented scientific code written on the spur of the moment to check out a new idea. If it works, write a little MatLab wrapper and release into the wild. FUN!!
Yes, we teach our students how to gather requirements, write documentation, carefully craft the code. However, quite a bit of our own code is written quickly, and the scientific paper serves as the documentation. One reason we get away with it, is that many of our programmes are really rather small snippets reading data, applying the new algorithm to it, and writing some output. In many cases, the code does not get released as production code. Only in larger scale efforts do we apply any thorough software engineering skills.
So, us academics often don't abide by our own rules.
Mea culpa, mea culpa, mea maxima culpa!
During my uni days someone on my software engineering course complained about having to do loads of "management stuff" when he just wanted to play around learning new languages. After we left I got a job with a large and somewhat bureaucratic company where I find the "management stuff" comes in quite handy and I actually wish I'd paid more attention. Coding is obviously an important part of software development work, but you also need to know among other things:
1. How to find out exactly what the customer wants when all they've given you is a vague preference
2. How to manage large projects where there's more than one person involved
3. What components need to go where if it's a project that spans several systems
4. How to write it all down in a form so that the managers doing your appraisals and deciding whether or not to pay for a project can understand it
Some of the more academic bits of software engineering are a bit esoteric for commercial use. I got blank faces when I asked about Jackson diagrams in the first few weeks of my job, and UML kind of came and went. However it is useful to be able to understand what on earth Oracle is going on about in their PL/SQL syntax diagrams. I don't have much use for database predicates using Greek characters but it is useful to know a bit of set theory or normal forms when you're working with complex databases.
Completely agree.
And another useful skill is being able to quickly create non-functional, mock-up applications. These are useful for presenting to the managers, etc as discussion points.
Being able to present a 'story' of how the problem is being solved is very important. Clear naming, some simple diagrams, an overview document can all help to get everybody (managers, IT manager, users) all on the same song sheet.
You are f* kidding me. The textbooks are worst offenders in bad quality code, with no respect to any of many constraints of real world code. Exception safety? No, we don't tech that in this chapter, move along! Use of standard algorithms? Why, everyone can write perfect quicksort by hand (haha!)! Synchronous I/O in supposedly high-performance code? But of course, we don't want to make it complex! Ignoring OS API return values? Sure, no one needs them! Use of design patters for sake of design patterns? Everyone is using them!
I could go on. The point is that, unfortunately, few of really good programmers work in academia or write textbooks (or teach). They have family to feed, mortgage to pay etc. etc. and so they need well paid jobs.
[Thinking in Java] is generally a pretty good book, but it substantially ignores good layout of Java - for which there's a specification - to save lines on the printed page.
Some stuff in the spec isn't even in Java, only in C, and some stuff that's in Java now isn't in the spec (when I last read it, about a year ago), but it's still valid. (Unstrictly speaking.)
Also the author has quirks (and doesn't even like Java any more, I hear), and all his examples use his personal set of macros which I'm pretty sure don't add anything in modern versions of Java and maybe never did, except perhaps to look more like C. Or not.
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2024
