Are You Proud of Your Code?

An anonymous reader writes "I am downright embarrassed by the quality of my code. It is buggy, slow, fragile, and a nightmare to maintain. Do you feel the same way? If so, then what is holding you back from realizing your full potential? More importantly, what if anything are you planning to do about it? I enjoy programming and have from a young age (cut my teeth on BASIC on an Apple IIe). I have worked for companies large and small in a variety of languages and platforms. Sadly the one constant in my career is that I am assigned to projects that drift, seemingly aimlessly, from inception to a point where the client runs out of funding. Have any developers here successfully lobbied their company to stop or cut back on 'cowboy coding' and adopt best practices? Has anyone convinced their superiors that the customer isn't always right and saying no once in awhile is the best course of action?"

Comments

Something to note about other people's opinions

[suso]

One thing to keep in mind when determining the quality of your code is that other people will most likely criticize the quality of your code. Usually saying that it sucks, when usually its just the person having their own way of doing things. I don't know why this is, I think its just human nature.

I've seen time and time again programmers taking over for other programmers' code and saying that the previous person's code sucks. Its like a right of passage or something.

Re:Something to note about other people's opinions

[JustinKSU]

Codes is an expression of the programmer's though process. Everyone thinks in a different way. Invariably the last person's code will seem to suck because you have to think differently to understand it. Patterns were developed to create a common ground where people can think about problems in a similar way. Regardless of how pointless and off track a project might be you still should be able to design reusable concise code if you follow the right kind of patterns.

Re:Something to note about other people's opinions

[Anonymous Coward]

I had this problem with a guy that was complaining that my code was full of GOTO statements, used all global variables, and didn't have any comments or subroutines. Bah, it worked so why should he bitch about it?

Re:Something to note about other people's opinions

[Chatsubo]

A lot of the time you find that, while someone is still employed, they do a good job of hiding their mistakes and covering up. It's when they leave that things start to go downhill because now suddenly, someone has to go read and understand their code. Then you realise it's a patchwork of quick fixes and bad design, and decide nice clean rewrite is in order.

At this point you try to justify the change to management, who will "schedule it for sometime next year", since this is not causing them any pain, only you get that priviledge. From that point on, you're stuck with someone else's bugs forever.

Now you're upset and become very vocal about the problems you now have to deal with.

There is a difference between "different" code that works, and bad code that routinely causes problems.

Usually the cracks show about a week or two after the guy leaves. And by cracks, I mean serious, client affecting shit.

Re:Something to note about other people's opinions

[noidentity]

Here are some pet peeves of mine involving dealing with other people's code. I don't think many of these are subjective either.

• Header files you can't #include without getting errors because you didn't #include something it requires (but stupidly doesn't #include itself).
• Lots of global variables that are read and written by several modules.
• Header files lacking comments about what functions do.
• Use of non-standard names for types with a fixed number of bits, instead of those from stdint.h/inttypes.h. So they have u16 or int16 instead of int16_t. Or really stupid stuff like uint instead of unsigned int (or just unsigned, which is equivalent).
• Lack of const-correctness. Something like void print_string( char* str ); Huh, does it modify the string? No, then why does it take a pointer to non-const?
• Unnecessary non-portability. Don't use #include unless #include isn't sufficient.
• Internal things put in header files. If it's only used in the module, keep it in the module's source file only! Same goes for not making internal functions static, opening the possibility of clashes.
• Files indented with two spaces instead of a tab, or even just one space. Fortunately this can be worked around with tools.
• Unnecessarily space-taking comments about a function's visible behavior. Things with lines of stars around everything, etc.
• Lack of structure tags, preventing forward declaration. Don't do typedef struct { ... } foo_t; do struct foo_t { }; and a typedef if necessary.
• Macros for integral constants (yes, even in C), since enum does the job and obeys scope (yes, C has different scopes, not just C++).
• Fundamentally, things that aren't highly modular and can be understood and used in isolation. I want to combine modules and have a minimum of complexity increase due to this combination.

Re:Something to note about other people's opinions

[CmdrGravy]

No wonder, that's a really old fashioned way of doing things. You need to get with the times and functional programming. Personally I do all my programming in functions, often I just need 1 or 2 big functions for a program if I make sure the functions all behave entirely differently depending on the values of the 30 or so parameters I pass to them. It's very efficient and yet still people moan !

CalcCallWaitingTime StripIllegalCharacters CreateInterfaceToACD DrawCalendarOutline may well be quite a long title ( often it's easier to acronymise them before I hand the code over ) but it's amazing the number of loops you can reuse if you have enough switches.

Re:Something to note about other people's opinions

[LiquidCoooled]

I often find passing the function name itself as a parameter helps with loop re-use.
That way you only need to create a single do loop and allow your cx(...) sub (result passed back in the 14th argument unless the 3rd is "E" or above in which case its pushed onto the reference you passed as arg[19 + val(arg4)].

The last guy who tried to use the code was so awestruck with my genius he passed out!

Re:Something to note about other people's opinions

[computational super]

But your code, of course, draws gasps of admiration and awe from all who look upon it.

Come on. When was the last time you had anything good to say about anybody else's code? Ever? All programmers say all other programmers are incompetent. And typically, management believes us.

Re:Something to note about other people's opinions

[Mr2cents]

I think part of the problem is that programmers lack the courage to just think. I recently had a programming problem that I thought two weeks about. That's go to work, think, write down some key ideas, pitfalls, things to do etc. on a piece of paper and go home. After these two weeks I had three A4 papers with some text scribbled on it. Then I spent one week coding, and when I finally tested it it worked from the second time (one small bug found).

In my experience, not everybody dares to work this way. It is a bit embarrassing if your boss enters your office and you're just leaning back in your chair, day after day. But on the other hand, if they wanted someone who would always seem busy, they hired the wrong person; they should have gone for a typist. Thinking is an important part of a programmer's job.

A second advice would be to keep abstractions as simple as possible. Think "What do I need and what API do I need to do that?". If you can get away with an API with only an init function and a "worker" function, then be my guest! K.I.S.S. is very important. Again, to make things as simple as possible requires a lot of thinking.

And while you are thinking it helps to have enough experience to have a "mental compiler". I can write and test code in my head so to speak. But that is something you only get after many, many years of intensive programming.

Re:Something to note about other people's opinions

[SilentBob0727]

Over-commented code (the kind where there's 2-3 lines of comments for every one line of code -- not every closing brace needs a reminder that we're exiting a code block, thanks!) is pretty awful too. I've met people of the agile variety who insist that well-written code needs no documentation: that if you carve your code up into small, tight, appropriately named classes and methods it becomes obvious what your code does and your code becomes "self-documenting", and I've met people who won't even look at code unless every single line is commented telling them precisely what it does, so "int i = a + 2;" has to have a comment above it saying "// create a signed 32-bit integer variable, i, and assign it two more than the value of a".

The former is wrong because while it's great that we now know what each little piece of your code does, it's still a challenge to see the forest for the trees in all but the most trivial cases (it also means that after several refactors you end up with a whole lot of miniature orphaned functions littering up your code that are never called and that do nothing but that everyone's afraid of deleting). A good method name doesn't tell the reader why the method is there or what its intended usage is. The latter is wrong as well, because suddenly naturally flowing code is broken up to the point where comments become a distraction and make the code harder to read (incidentally, this is why I started using justified end-of-line comments... it helps with the distraction).

You should always comment your classes (or your data structures if you're using a non-object-oriented language) -- state the reason they exist, what requirement they fulfill, their role in the application, and any caveats to using them. Comment your constants, class and instance variables if it's not bleedingly obvious from the class description what purpose they serve.

Comment your public methods! Your public methods are essentially the exposed API into your code, so if you want your successor reusing code you wrote rather than writing his own that does the exact same thing, it had better be absolutely clear how it is to be used. At a minimum, this should include what the method is there to do, a detailed description of each parameter to the function, and any constraints on the parameters, side effects of invoking the method (Does it write to any files? Set any external variables? Allocate or free any memory?), the range of values that can be returned, a description of any special return values, and any exceptions that can be raised when calling the function. Comment your private methods as well, though with your private methods you may be justified in just explaining why the method is there.

And for the love of God, don't comment your private variable accessors unless they get or set in an unusual manner. And you don't have to comment constructors that just assign parameters to instance variables.

Finally, while those agile guys are right in that your code really should have a natural flow and speak for itself, you should still comment your runtime code. Longer functions should be divided up into "paragraphs" with comments stating what's about to happen and how the current state contributes to the overall goal of the function. If your functions have extremely clean divisions of functionality, consider breaking them up into smaller private functions unless you're concerned with every last ounce of performance and can't afford the 10-20 cpu cycles necessary to do a function call (or declare the methods as inline). If you're doing something in a manner that's unorthodox or not immediately readable or that will make someone reading your code go, "what the hell?", either rewrite it (=D) or comment it to justify why you feel it was necessary to do it that way.

Automated unit tests can also be a good supplement to well-documented code, as they give natural examples of code usage and can serve as tutorials for people trying to learn your code. Often this displays intent a lot better than comments can, since doing is often more effective than saying.

I find people are more concerned with whether code is commented "enough". I think it's better to be concerned not with the amount, but the quality of comments.

Re:Something to note about other people's opinions

[SilentBob0727]

This is a false analogy. Human language is symmetric in that it is designed to be produced and consumed by a human. Programming languages, on the other hand, are asymmetric in that regard. As such, reading a computer program requires a certain amount of aptitude that's better suited to a computer -- for example, tracking the entire program state at any given time. Granted, you only have to track the state that's relevant to the current context, but recursively switching contexts (see function call, go look up function, finish reading function, go back to function call, keep reading previous function) is something a computer does well and a human doesn't do well.

Also, humans tend to read left-to-right, top-to-bottom. Any worthwhile program is filled with loops, branches, conditionals, calls, recursion, etc. As the program size grows, it becomes very difficult to sit down with the uncommented code and just read it, and actually take away the general gist of what was just read. To do so requires several sessions of hard concentration and focus, and time to reflect on and digest how it all works together. Well-structured, well-written code can only go so far.

Comments, in many cases, make up for that lack of aptitude. It's not restating, it's clarifying what the code does so as to make it less likely for the reader to get lost and help speed up the learning curve.

Re:Something to note about other people's opinions

[Anonymous Coward]

But I'm saying that well written code does not need clarification.

Here's some well-written code:

                int nIMin = m_nIMax;
                int nIMax = m_nIMin;
                int nJMin = m_nJMax;
                int nJMax = m_nJMin;


So is it a bug? I can hear you protest now that you'd need to see it in context to know. But if I add a single short comment:


                int nIMin = m_nIMax; // initialize to opposite ends of range
                int nIMax = m_nIMin;
                int nJMin = m_nJMax;
                int nJMax = m_nJMin;


you know that my intent was to initialize max with min and min with max.

There is no way to express this in the code itself, and this kind of situation crops up all the time in well-written code of even moderate complexity. People with limited imaginations, who lack the capacity to see that their code could be read in many different ways, are generally unable to grasp this point, even when presented with multiple examples. Sad, really.

The virtue of constraint, and other musings...

[Max Romantschuk]

I seem to find that trying to code more slowly than I could helps a lot. I'm not the most efficient coder there is, but I tend to produce less bugs and have more time to make better design decisions when I slow myself down.

I've had several jobs where I've found that although management never seems to approve of a slower process in itself, they do begin to see the values once they notice that my code tends to be less buggy than that of my peer programmers.

As for turning around bad practices... That's always hard. Culture is a tricky thing. But it helps to use analogies, lots of analogies! System grown too large with too many kludges? Compare to building a skyscraper on the foundations of a cottage. Management wants to speed up a project by senselessly adding more people? Compare to: "One woman can make one baby in nine months. Two women can make two babies in nine months, but two women can't make one baby in four and a half months..."

Be creative, be thorough, and be proud of your work. Always try to make the next iteration better, but also remember that sometime meeting the deadline is all that counts.

My two cents, I guess...

Lost out

[gaou]

"It is practically impossible to teach good programming to students that have had a prior exposure to BASIC: as potential programmers they are mentally mutilated beyond hope of regeneration."
Edsger Dijkstra

Sorry mate, there is no hope :)

Yes

[Average_Joe_Sixpack]

I often use "Programmer: Alan Smithee" in the comment header

Sorry, I have to bite about this.

[Fross]

I am one of those people who likes lots of code. So much so that I've developed a style, similar to how I used to code 68k assembler, of running comments down a second column (usually 40-60 characters in) that describes what is going on. After all, it doesn't interrupt the flow of the code, and if you're editing Java on an 80-column fixed-width interface, you're doing it wrong to begin with. I wouldn't say I comment every line, probably one in every 3. However, this gripe with over-commenting is fundamentally flawed:

and I've met people who won't even look at code unless every single line is commented telling them precisely what it does, so "int i = a + 2;" has to have a comment above it saying "// create a signed 32-bit integer variable, i, and assign it two more than the value of a".

Why on earth would you write a comment like that? That is ridiculous. However, the line DOES need a comment. It's declaring a variable with a non-descriptive name and doing something specific with it. Now, the comment should do something like say what the variable is used for, if it's non-obvious. In this case, "int i" is usually used for loops, so it doesn't need a comment unless it's *not* used for loops. :) However, if it was being used in a loop, why is it being set to a+2? Is a some sort of offset in an array? Is it a user-entered value? THIS is what the comments will illustrate, eg:

int i = a + 2; // skip the first two elements in the loop as they contain other data

or

int i = a + 2; // user input will be off by 2 because of (strange reason here)

writing comments like "initialise variable" is useless, but thinking that may be all there is shows a misunderstanding about how comments work.

You can assume the person reading your code is a programmer, familiar with the language used, and able to follow general program flow. However, he may not be familiar with the rest of the system, nor with any specific tricks you may use[1]. Comments should be like a director's commentary on the code, pointing out what may not be obvious, and giving the bigger picture - the reason why a specific variable is used a certain way, or what a messy few lines of code may be achieving, eg: // now split the input into an array and parse ready to give to the file handler
(horrible loop declaration here)
(even more horrible regex here)
(custom function calling here)

It's said comments are like sex - even when they're bad, they're still pretty good. I'm pretty sure I've never spent 3 hours trying to work out how to get THAT to work, though!

[1] eg, I use a relatively uncommon trick in Java doing string comparisons of if(!"blah".equals(myString)) because it can't fail on the null pointer check that if(!myString.equals("blah")) can. A simple example, but something more complicated will save someone time if it just has a quick comment next to it saying what that section of code is achieving.

That's Not Good Code

[severoon]

The biggest thing I see wrong with other people's code is not at the syntax level or to do with commenting. It's based on a misunderstanding of basic CS principles. An example is in order from last week...

In the codebase I work on, there's a module that analyzes documents and tags them, assigning different weights to each tag based on relevance. (Think of the way google works--it reads a web page and tags it with terms, then if you type in one of those terms while doing a search that document comes up--yes I know this isn't the way google actually works, save it. :-p ) At one point we send a list of tagged documents from one system to another, and this area was the source of many, many bugs. The responsible developer spent the better part of last week slaving on this code and every change seemed to introduce more bugs than it removed. Finally, I got involved to see what the problem was.

Here is one thing (out of many) that I found. After the docs arrive in the new system, each doc is supposed to be persisted along with the top 5 most relevant tags (the rest discarded). The code was written to create a Document, check a hash table that maps the doc to the number of tags it currently has, add a tag if that doc doesn't yet have five, then increment the value associated with that doc in the hash table. When I saw this, my head almost exploded. At some point, this developer thought it would be a good idea to create a hash table and keep this information, information which is available in the document itself (he could've just called doc.getTags().size() to see how many tags it currently had). Now he created this hash table and all his code was written to depend on it, so of course he had to write a lot of code to keep it in sync with the state of all these documents.

This sounds like a simple enough thing, right? It's not necessary, and it's not the best thing, but it's a fairly simple mistake and one that couldn't impact code readability all that much, right? Maybe--but consider that this is one of about 10 simple mistakes I found, and you can imagine the explosion of interactions of all these simple mistakes...and that's why we burned a person-week on something that should've been trivial. When I pointed out to this developer that he could just get the number of tags directly from the doc itself, and doesn't need to keep this state in some other object too, he said something to the effect of, "That's a different approach, but whatever...one's not better than the other."

But one is better. If this developer understood the difference between intrinsic and extrinsic, he never would've written that code in the first place much less defended it. To put a fine point on it: the number of tags associated with a document is intrinsic to the document itself, so that is where the information should live...not there as well as some hash table somewhere. The document is the authority and the final word on how many tags it has at any moment in time. (There's a principle in databases called the SUA Principle--it means one should keep data in a Single place, in an Unambiguous manner, and that should be the Authoritative source of that data and no other. It applies here too.) Putting this info into some other object, even if that object exists solely for the purpose of tracking that info, means you're creating an object that stores information that is extrinsic to it. Never a good idea...now you need a whole bunch of supporting code that keeps the extrinsic info in sync at all times.

Let's say I'm designing a Ball class for use in a physics application that students learning physics can use. They can shoot the ball out of a cannon, put it under water, in deep space, on Jupiter, etc, and see how the simulation behaves. As the developer of this class, I decide to add a characteristic to the ball that keeps info about its "heaviness". What should I add, a getWeight() method or a getMass() method? The developer I was talking t