Collaborator-8-3-CTA-banner

Your Code May Work, But It Still Might Suck

junk code

Why one of Steve Jobs’s guiding principles should also be yours. And also: What you can learn about code quality from Doom’s source code.

In his revealing biography of Steve Jobs, Walter Issacson told of Jobs’s fastidiousness when it came to product details, even the stuff people would not see. Jobs demanded the unseen features be as finished and polished as the visible.

Look at the chip layout on an old Apple II motherboard, laid out in perfect, neat order. The original Mac case had the designers’ signatures inscribed inside, even though the case was sealed. The NeXT cube also had a black matte finish internally, even though the user never saw it.

Jobs would never accept the “No one will ever see it” attitude. “For you to sleep well at night, the aesthetic, the quality, has to be carried all the way through,” he told Issacson.

That attention to detail and craftsmanship is one thing Jobs had in common with John Carmack, co-founder of id Software, who is widely regarded as one of the world’s most talented and influential game developers.

Jobs was not big on games and Carmack once described his relationship with Apple as uneven. “I’ll be invited up on stage for a keynote one month and then I’ll say something they don’t like and I can be blacklisted for six months,” he once told the game site Kotaku.

But Carmack and Jobs shared a work ethic. A look into Carmack’s work reveals a fastidiousness and structure of which Jobs would approve. It’s one of the many reasons Carmack is so lauded by both game developers and geeks.

The attention to code quality isn’t only internally, for the stuff that “nobody will see.” id Software has a tradition of releasing the source code of old game engines as open source (the whole collection can be found on GitHub). That lets would-be programmers study how the software is constructed and allows advanced coders to modify or port the older games to other platforms. id provides no support; you download the code and are on your own.

The results are often spectacular. id games are ported to other platforms, usually Linux, and individuals or groups make all kinds of modifications to the game. People who make a particularly strong impression often find work within the gaming industry this way.

Late in 2011, id kept with tradition and released the source code for what it called “id Tech 4,” the game engine used to make “Doom 3,” “Quake 4,” “Prey,” and other games, all of which are no longer sold.

Programmer Fabien Sanglard did an in-depth examination of the code, as he has done for a number of other games, and a few months later, Kotaku did its own ode to the code, talking of the “exceptional beauty” of the Doom 3 code.

Exceptional beauty. Wouldn’t you like to learn that someone praised the software you wrote in that manner? Herein, we look at the significance of keeping your code clean and making it literature, not gibberish. Because you cannot take the attitude that “No one will see it.”

Everyone sees your codeEveryone Sees It

The fact is, other people do see your work, and that includes yourself. Do you think you can remember everything?

“I tell my students: Six months from now you are going to have to modify that code. And you’ll appreciate the fact that you took care to assign easy-to-understand variable names, insert insightful comments, and use proper spacing and indenting,” said Bob Makarowski, an instructor with the Technology Programs at Baruch College School of Continuing and Professional Studies.

Dr. Mark D. Pardue, CIS department head at ECPI University, has the same experiences with students, who for some reason have never understood the importance of maintenance. “They say, ‘Yeah I know what it does.’ I say, ‘You probably won’t remember why you did what you did six months from now when you have to do updates.’ They respond ‘Well, I won’t have to.’ I say, ‘Yes you will,’” he said.

Unless you completely replace the code with a new version, your code will always require updates. You might need to add new components. You may run into bugs. If the code is an unreadable mess and poorly commented, will you even know your way around?

“If everything is gibberish, it makes it impossible to do that fix. So we tell our students you will have to update code. It needs to be able to be looked at by you or anybody, and they ought to be able to tell what it does, why it does what it does,” said Pardue.

Makarowski adds that in a professional environment, no man is an island and neither is his work. “The sad thing about programming is it attracts loners, people who want to sit in a cube and write code. Those days are over,” Makarowski said. “To survive as a developer or a business analyst you have to be an excellent coder, you have to be a business analyst, and you also have to manage others. You have to manage your teammates,” he said.

And a bad coder can poison the well, said Mike Kennedy, an instructor with Developmentor.com, an online code instruction site. “The best developers, even if they write better code, if they get into a system with five other guys and those five others are creating junk, there is no motivation to be careful about your craft and write code that is flexible and modifiable. You’re building good stuff and they are piling junk on it. It’s demoralizing to work in a codebase where you’re the only one who cares about code quality and craftsmanship,” he said.

Coding habits are often a reflection of the person, said the teachers. “People take care of their own bodies like they take care of their own programs. If they are clean and well groomed, their code is neat and easy to understand. If they are slobs, their coding is going to be sloppy,” said Makarowski, and both Kennedy and Pardue concurred with that sentiment.

“I don’t know that you ever completely break them of that, but when they keep getting poor grades on program submissions, they kind of get the message,” said Pardue. “When you say you got a D [grade] because it’s poorly commented and spaghetti code and you say, ‘But it works,’ you say, ‘Yes it works, but your assignment was to write clean, well-documented code.’ It has to be a job requirement in the workforce or they will continue with their old habits.”

Comments vs. Readability

One of the reasons the Doom code is so readable is because it’s so clean and well structured, as Kotaku noted in its evaluation. That’s because Carmack set up a Coding Style document (ftp link) that serves as a guide for his programmers, much as journalists have writer’s guidelines. The coding style guidelines include:

Variable names start with a lower case character.

float x;

In multi-word variable names, the first word starts with a lower case character and each successive word starts with an upper case.

float maxDistanceFromPlane;

Typedef names use the same naming convention as variables, however they always end with “_t”.

typedef int fileHandle_t;

For much of its existence, id was a very small company with small programming teams. The company’s groundbreaking game “Doom” was done with four programmers, while “Quake” was done with three (Carmack being one of them in both cases).

By the time Doom 3 was underway, Carmack was Technical Director and had five programmers working for him, so he created this guideline. That made a big difference, said Kennedy.

“I think it’s really important to agree on those things [beforehand],” Kennedy said. “Because they are arbitrary things (names end in _t or start with idCLASSNAME, etc.) you would never arrive at a common codebase like they have by accident or organically.”

Kennedy said guides are common, but not to the clear and explicit length Carmack went in his guide, and that makes the difference. “It’s common [to have guidelines]. Whether or not they have it clearly spelled out is another thing. Sometimes it’s just a verbal agreement, sometimes it’s a solid doc,” he said.

Comment Sense

Part of the Doom 3 code “beauty” was its minimal use of comments. The teachers find that comments are often used as compensation for poor code.

When he teaches, Makarowski forces students to use common-sense variable names and common-sense module names. “And I am not a commentator. There seems to be an anti-commenting movement a few pros are on. A few well-placed comments can make a program easy to modify and easy to improve.” Think of the poor schnook taking your place, when you move on to greater glory.  “That’s why you name variables with common-sense names and use comment codes to place enlightenment on what you have done.”

Too many times, students write ‘string variable’ for string variables in their comments. That’s not enough, said Makarowski. “Tell us what you are doing with the code. Because you may not be the one fixing it later; and even if you are you won’t remember everything you’ve done over the last six months to a year,” he said.

Kennedy cites a phrase from programmer and author Martin Fowler called “code smells.” A code smell is something that’s not broken, but is not quite right. It compiles, but just doesn’t “smell” right.

“If you see a lot of comments, that’s considered a code smell because comments are almost deodorant for other code smells. So if you are writing something bad and think that’s not understandable, let me put a comment to say what it does because I can’t look at the code and understand it. When I write code, instead of writing a comment trying to explain this, I say, ‘Let me try and write the code better,’” Kennedy said.

Clean Up the Slop

Sloppy code has obvious problems: The software probably won’t run well and it’s hard to clean up. But it generates other problems as well. It’s demoralizing for any developer to deal with that mess. “Aside from the monetary rewards from good programming, there is a feeling of accomplishment programmers feel when something works. Sloppy code slows down the road of accomplishment of picking up someone’s work and making sense of it and modifying it,” said Marakowski.

For programmers who inherit a project that’s been around 10 years and it’s hideous, Kennedy recommends the book Working Effectively With Legacy Code by Michael Feathers. In it, Feathers recommends carving off pieces and make them important rather than taking on the whole project at once.

“If you’ve already got hideous code, you aren’t doomed; you can work effectively,” Kennedy said.

See also:

Comments

  1. I believe “code smell” comes from Kent Beck, not Martin Fowler. The wikipedia article says: The term appears to have been coined by Kent Beck on WardsWiki in the late 1990s. Usage of the term increased after it was featured in Refactoring: Improving the Design of Existing Code.[1] Code smell is also a term used by agile programmers.[2]

  2. tl;dr

  3. I agree that great software developers must write code that others (perhaps not so great) can understand. I also understand the frustration with code comments. It is hard to tell a story about your code using code comments and we don’t really have the opportunity to write these stories down anywhere else. I am trying to change the way we create narratives about software development with a new tool: 
     
    http://www.storytellersoftware.com 
     
    With the Storyteller tool one can replay coding sessions, filter the uninteresting parts out, and write a narrative about what happened and why. 
     
     

  4. Graham Polley says:

    Nice article. I have been involved in projects in the past where just a handful of good guys actually take pride in their code and never check junk/mess into the repo. But when the majority of the team just don’t care it is quite simply soul destroying! After a while you give up and the broken window theory kicks in. Unless a project is kicked off with clear coding quidelines from day 1 and comprises of good developers, the code will always end up a mess.

  5. I laughed loud when you said that even the PCB of the Apple II was controlled by Jobs. Do you not know that all PCBs are designed this way due to signal routing physics?

  6. Hey, alex, 
     
    ts;su

  7. One of the better articles I have read about code quality!

  8. My definition of legacy code is code with insufficient use of dependency injection. While I agree Michael Feathers’ book is amazing, I suspect he’s going a bit too far, with respect to cleaning up codebases. Most of the benefit of high quality automated testing isn’t really in the “tests as specifications”. It’s in breaking up whole chunks of code, so they are self contained, so that you minimize unintended side effects. Unintended consequences are the main reason legacy code is so hard to modify.

Trackbacks

  1. […] Your code may work but it still might be bad […]

Speak Your Mind

*