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

Getting better.

[Ihlosi]

It is buggy, slow, fragile, and a nightmare to maintain.

When looking back at my first project, I feel the same. But I also think that I've learned a lot from it, and all subsequent projects were much, much better.

So, by being "not proud" of your code, you've made the first step towards improving it.

Re:Getting better.

[RandoX]

If you start coding from the beginning with the best possible methods, then congratulations. If you're like myself, and most of the rest of us, you're learning better ways to do things as you go. I know that I can't help but look back at older projects and think that there are better ways to do what I've done. Now I know better. Now I'll write things in a more efficient and maintainable way. I can only hope that in a few years I'll look back at the code I write this week and have an even better, cleaner, faster, and more maintainable way to do it.

More Design

[Loophole64]

Often times you can avoid a lot of this headache by spending more time in design. If you can flush the project out in some detail during design, and include the customer, more of those changes will be included in the original design before you ever start to code. Unfortunately, others in your organization will often feel like design time is wasted time. You have to be steadfast in your will to spend time in the design phase.

Re:Something to note about other people's opinions

[Atraxen]

For the sake of the wider conversation, let me remind folks that there are still cases where (nearly) every cycle counts. One that comes to mind is is scientific computing (e.g. molecular modeling, !e.g. most analysis). So, if anyone's still missing "ye good 'ole days", there's still a need for 'Shakespearean' code...

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.

Re:Something to note about other people's opinions

[JavaRob]

But I'm saying that well written code does not need clarification. When it's well written there's nothing more that can be said in any other language that hasn't already been said directly in the code. I'll admit there are border cases where it's almost impossible to write code that is abundantly clear Have you never been brought on to maintain a large codebase that you didn't write? Even if it's *beautifully* elegant and refactored to a sparkling shine of perfection, you're still going to be lost in large sections of it for a while. There's going to be project-specific terminology decided by the developers in variable & class naming that you'll have to learn, and you simply cannot always glance at a single shard of an enormous project and comprehend where it fits into the whole. Ideally, you're going to have a whole lot of relatively independently functioning little parts, right?

Suppose you have an exception raised in a given class. You know the line number, and you open the class... if it's involved in serving a purpose that's low-level enough, it's going to take you a far more time to figure out what it's for, how it's used, and what role it plays in the project as a whole if you don't have, say, 3 simple lines of plain English in the header comment.

Personally I don't write too many comments in my "normal" code. I write progressively more as the code gets more complicated -- some features are simply too complex to even fit the implementation in my head all at once, so I write a shorthand walk-through of the implementation before I start. When I'm done, sometimes the code has actually boiled down enough that I can chuck that (sometimes I'm not so lucky).

You have to comment implementations that "look wrong" or are counter-intuitive, possibly because of client demands ("the last software package did it that way, so our other systems are designed to correct for it..."). What, are you naming methods calculateScaleWronglyPerClientRequest()?

It can be wise to flag methods (or classes) that will *appear* unused to refactoring analysis, because they're loaded & accessed dynamically.

I could go on.