Give a code monkey a ruler...

July 28, 2008 9:24 AM

How do I make code LOOK beautiful? Occasionally, I see these snippets of code where everything looks very aligned and orderly, the variables all seem the same length, the functions are all neatly aligned. My code on the other hand always looks rough and shoddy. What do the people with neat code do to make it look so neat?

I'm thinking about C++ here, but this applies to most types of code. Are there any rules I should be following to make my code also look so neat?

posted by markovich to computers & internet (13 comments total)

I use a code editor with automatic indentation, Emacs. I can press tab on any line and instead of inserting spaces, it automatically re-adjusts the line so that it's indented properly. I can even select all the code in a document and Emacs will reformat it.

I would suggest reading Code Complete by Steve McConnell, which is a book dedicated to the basic principles of software construction, and one of three books sitting on the table in front of me right now.

Ahead of time I try to think of a naming convention that I like for my variables and functions then try to stick to it for that project. Finally, I go back a lot and re-edit code that I've written, replacing variable names that no longer make sense.

Like writing a book, your code will never be absolutely perfect, it's a matter of continuous refinement.
posted by onalark at 9:29 AM on July 28, 2008

I think the standard reference is Code Complete. Specifically, chapters 31 and 32 have lots of tips and rules on writing nice looking code (rules for indentation, comment formatting, variable naming, etc.).
posted by Jasper Friendly Bear at 9:30 AM on July 28, 2008

Just off the top of my head...

-organize your files in sections (eg: #includes first, then preprocessor statements, then typedefs, then constructors, then member functions (in the same order as in the .h file) and so on...)
-be consistent with indentation
-be consistent with braces and parenthesis
-be consistent with whitespace including before and after ( and )
-have a good variable naming convention
-no magic numbers or strings
-maybe separate all member function definitions with some sort of //----------------------- type thing
-clean your files before checking them in

Just little things that add up.
posted by jon_kill at 9:31 AM on July 28, 2008

Most C compilers come with an attendant program called "cb" which stands for "C Beautify". You run your source through it and it does all that formatting for you.

Having said that, I never needed such a program because I developed good coding habits early.
posted by Class Goat at 9:31 AM on July 28, 2008

Always use 4 spaces for tabs instead of an actual tab character -- most good text editors will do this for you. This, in my opinion, is the most important thing for clean code. Otherwise you end up with mixes of tabs and spaces depending on who edits it, and nothing looks aligned, especially on pastebin sites and forums.

If you really want uniform variables, you can go for something like Hungarian notation, but in my opinion, descriptive names make code more beautiful, whether or not they're all the same length.

One trick a developer taught me was to put comments explaining a conditional inside the conditional instead of above it. That way they read better, even though when you're initially coding, you'll probably put the comment before the if(). So instead of:

/* Tell the user if foo is bar. */
if( foo == bar )
{
    fprintf( stdout, "Foo is bar." );
}

do

if( foo == bar )
{
    /* Foo is bar, so tell the user.*/
    fprintf( stdout, "Foo is bar." );
}

As the above code shows (sorry for the C, I don't do ++), I'm a fan of putting spaces between parentheses and what they contain, and of putting opening braces on separate lines from the code that calls them. To me, it looks cleaner, but it's certainly a matter of debate.

Try looking at the coding conventions of various open source projects. Because they require collaboration, they often formalize good formatting techniques into their coding style guidelines.
posted by jbrjake at 9:39 AM on July 28, 2008

Ages ago (early 80s), writing a code formatter (like "C Beautify") was an assignment for students in Pascal classes at Umass Amherst. Back then, we called it "pretty print".

For the most part, these things are taken care of by your editor and habits :)
posted by jdfan at 9:40 AM on July 28, 2008

Use something called a "code beautifier", sometimes called a "pretty printer", or "code formatter". Most decent editors have this feature. The most basic beautifiers will just indent the code consistently. More sophisticated ones will understand a little more about the code than just the indentation/formatting and can order various elements in code (that jon_kill) logically. The most sophisticated formatters allow you to configure the formatter according to your preferences.

It's a good practice if you are working on a team to establish some team coding conventions and then use a formatter to automatically apply the formatting (often when the code is committed to a version control system). The tricky part is getting everyone to agree on conventions.

"Code Complete" is in its second edition and is a must-read for ANY software developer.
posted by kenliu at 9:46 AM on July 28, 2008

Many IDEs do auto-indent when you press the Enter key for a new line and whatnot. Of course, they don't solve all your styling problems, but having that auto-indent is a step.

That said, I second jon_kill's list, with an addition:
- make use of new lines for lines of code that are really, really long. There's nothing that bugs me more than seeing super-long lines that requires a lot of side-scrolling. Some languages like Python are sensitive to whitespace and indentation though, so be cautious about that.

And now I really got to get my hands on Code Complete.
posted by curagea at 9:50 AM on July 28, 2008

Looking at style(9) for Kernel Normal Form would be a decent place to start.

But yeah, you shouldn't be formatting your code manually -- in my opinion. It's just sort of a mechanical waste of time and get clobbered whenever you make a nontrivial change.

I would just find a decent plugin for whatever IDE/Editor you're using to pretty print your C++.
posted by godisdad at 10:19 AM on July 28, 2008

On the first pass of variable naming, make sure the names, while maybe not perfect, are unique enough to be globally replaced without ambiguity. Once they are all in place think twice about how to make them as clear as possible.
posted by StickyCarpet at 11:21 AM on July 28, 2008

Honestly, you use an IDE that formats for you. And that will fix up the indenting by pressing CTRL-I.

Also, an IDE that supports refactoring really helps with good variable names. You aren't as afraid to change something because of possible breakage from doing it manually.
posted by smackfu at 11:27 AM on July 28, 2008

Pick a maximum line length and stick to it religiously. Do everything consistently as others mentioned. Avoiding abbreviations helps.
posted by jewzilla at 11:53 AM on July 28, 2008

Much has been said

but don't do this

if(foo==bar){ ...

}

do

if(foo==bar)
{
...
}

Don't use obvious comments

// check if foo eqals bar
if(foo==bar)
{
...
}
posted by mattoxic at 5:44 AM on July 29, 2008