How to Keep Your Code From Destroying You

An anonymous reader writes "IBM DeveloperWorks has a few quick tips on how to write maintainable code that won't leech your most valuable resource — time. These six tips on how to write maintainable code are guaranteed to save you time and frustration: one minute spent writing comments can save you an hour of anguish. Bad code gets written all the time. But it doesn't have to be that way. Its time to ask yourself if its time for you to convert to the clean code religion."

Comments

Damn

[ReidMaynard]

Damn, that game looks sweet. Anyone know what it is?

That was just terrible...

[FortKnox]

That has to be the worst written article on cleaning up your code I've ever read.
This looks like it was written for (and BY) freshmen CS majors.

Comment your code smartly? No shit?
Use #defines everywhere? Honestly, I find that having a config file (or DB table) is a lot better, as I can change global variables without even a recompile...

I'm not saying its BAD advice, its just advice that anyone in the real world already knows.
How about something new?
1.) Use test driven development
2.) Write complete unit tests, including bad input
3.) If any piece of code is complex enough to require a comment, make it its own function and comment the function. I believe the only thing that REQUIRES comments are classes and methods. Not pieces of code...

I code go on, but I'm not a writer...
And neither is the author of that pile of trash...

Re:That was just terrible...

[AuMatar]

Not every program uses a db. In fact the majority of programs don't. And unless a constant is going to change frequently, or needs to be configured per client, putting it in a configuration file or db table is a bad idea. It makes it fairly likely it will be changed by accident. The only things that should be in configuration files are things you actually expect the user to configure per install.

As for your advice

1)Thinking about testing early- good. Writing unit tests-good. The test driven development mentality (write tests instead of design, write unit tests before coding)- bad. It leads to a lot of wasted time, completely rewritten test suites, and throw away work. Thinking about testing early is useful, it may cause you to think about corner cases. But writing them first causes 2 problems- you end up writing the code to solve the tests (rather than solving the problem) and/or you end up throwing away half the test suite in the middle when you refactor the design.

3)Disagree. The purpose of comments is to make sure that maintainers know what the code is trying to do. Anything block of code thats more than 5 or 6 lines deserves a comment. Breaking all of those into independent functions leaves you with hundreds of 5 or 6 line functions, which is even harder to understand how they interact. Frequently the correct thing to do is not break it into a function and just write a 1 line comment.

Summary: Beginners need tips too.

[Palmyst]

The article is suited for beginning programmers, I guess. Here is the summary of the tips.

1. Comment smartly.
2. Name your constants ("use #defines").
3. Descriptive variable names, but not too long.
4. Handle errors.
5. Avoid premature optimization.
6. Clarity is better than cleverness.

The author may not be a beginning programmer, but it appears that he might be a beginning writer on programming.

Expected Value

[dcollins]

"One minute spent writing comments can save you an hour of anguish."

However, what's the probability that the savings actually goes to *you* and not a coworker competing with you for a promotion, or someone who replaced you in a later year? If you work in an office with 100 staff, let's say 1%. So expected savings to you is EV = 1% x 60 minutes = 0.6 minute, less than the minute it takes to write the comment. (Even assuming the payoff is correct, and then helping competing coworkers doesn't do any damage to you.)

This is what I consider to be the "tragedy of the commons" for software engineering jobs. When I was a programmer, the people who did the least documentation were the fastest, and often the only folks who could approach certain parts of code, and so held in the highest esteem by the executives. Now I only write code for my own projects.

Mostly agreed

[ZorbaTHut]

I thought I'd make two comments on things that I think he got a bit wrong.

Tip 2: Don't use #define. Avoid it as best as you can. Use const int. That's what it's for. It will be typechecked by the compiler, it's much harder to produce bizarre errors, and 99% of the time it's better.

const int NUM_ALIENS_TO_KILL_TO_END_WAVE = 20;

Tip 4: Warning messages don't work. Don't bother with them. Use assert() - if it triggers, your program will crash with a useful error message. Now that's an incentive to make things work!

In my current project, out of 25,000 lines of code, I have almost 1100 asserts. And the first number counts whitespace. Any bugs I have get found and squashed pretty much instantly.

It was fine...

[Erasmus]

People who are just starting their careers as programmers are allowed to read articles too. Just because something is aimed at a population less experienced than you doesn't mean that it's crap!

I'm not sure if it really called for a Slashdot entry, but I've been on a few projects with new coders where a quick read of something like this on their parts would have saved everyone a lot of grief.

But C doesn't have classes or methods.

[wiredog]

It has functions...

Re:Who wrote that article?

[KingSkippus]

Maybe it was the note at the top of the article that says, "Level: Introductory."

Maybe it was the author's comment at the end that said, "At this point, you may be thinking, 'Wow. That was a big waste of time. All of this stuff is obvious and everyone knows it. Why did anyone write all of this?' I hope this is what you're thinking. Then you're already smart. Good for you."

But somewhere along the course of reading the article, I got the impression that he wasn't writing it for professional developers (at least, smart ones), but for people relatively new to programming.

But then, maybe I'm just stating the obvious, Cap'n...

Felt I should point out

[loqi]

... if your C code requires you to know the difference between i++ and ++i, it is too complicated

It's not a matter of knowing the difference, it's a matter of the code depending on the difference. If you need to increment beforehand, do it on the previous line. Afterward, do it on the next line. Expressions are like sex: they're better without side-effects.

Re:Who wrote that article?

[dvice_null]

I think all Slashdot readers should read that article. After all it tells you how to write good _comments_.

A Note From the Author

[spidweb]

As the person who actually wrote the article in question, I'd like to thank you for your comments and respond with a few of my own.

* To those who think it is all so obvious that I shouldn't have written about it:

No. You are wrong. Just wrong. Good programming practices do not just appear in peoples' heads as if by magic.

It's an introductory article. It's sold as an introductory article. And I am far more interested in being Right than I am scared of being Obvious.

* To those who have problems with suggesting using #define instead of const int

Meh. Yeah, you're probably right. But the important thing here is the CONCEPT of having your constants being defined in one central, easy to find place. Once a person has that down, he or she can define them however is desired.

* To those who accuse me of being a (gasp) inexperienced programming writer.

Yeah. So what? I never said I wasn't. I'm a game author. I've written over a dozen games. They all made money. That doesn't mean I am mister programming advice god.

But one, if you have a problem with it, yell at IBM, not me. They're the ones who had me write the piece.

Two. This is kind of ad hominem. Who cares how experienced I am or am not? I'm still right.

* I didn't read the article, but I'll say bad things about you because it means I'm awesome.

R0ck 0n d00d. First post!

* I liked the article. It might tell beginning programmers something actually useful.

If anyone says this, thanks in advance.

Re:Who wrote that article?

[spidweb]

A brief defense from the person who wrote the article.

The indenting in the selected code was not mine. It got screwed up somewhere between my machine and being posted on their site. I'll drop them a not and ask them to fix it.

No, I am not insane. :-)