Code Style
---------------

Comments are useful for telling people WTF this code is supposed to do, but there's another aspect to readability - formatting!

Most languages allow a programmer to write code that is perfectly legal according to the syntax rules of the language, but is nonetheless a snarled and unreadable mess. For example, C syntax doesn't care how much whitespace goes between statements, parts of statements, etc...just so long as the names have at least one space, it's generally still correct code. But! Reading code that doesn't follow consistent formatting rules tends to be difficult.

A few guidelines to get started:

-consistent naming: if you're going to name you variables in UPPERCASE, then keep them in UPPERCASE. If you're going to make long_descriptive_variable_names, then stick to the long_descriptive_variable_names style.

-newlines: use vertical grouping and/or separation to show the logical steps in your code. A quick-and-dirty criterion for this is to describe to yourself what it is the code is supposed to do, and group all the lines that make up the implementation in code (be it C++, Ada, Ruby, or whatever else) of each sentence in English (or Spanish, or French, or Ukranian...). Don't be afraid to put a lot of blank lines in if there's a chance it will make it easier to see what's going on.

-indentation: This one is pretty much universal - If you write a control statement of some kind, indent the code inside it. For-loops, while-loops, if statements, case statements, try/catch blocks...if it has starting and ending portions (eg, IF...ENDIF), then the code between them should be distinguished from the code outside. Different people will tell you different numbers for how many spaces to indent each level, and it's largely immaterial how many you choose.

-comments: Comments fill two main roles: Documentation, and Clarification. The simplest case of using comments is to describe what you just did or are just about to do. My own practise is to comment wherever I can expect to need an explanation when I come back two months later and have no idea what I was thinking. As for documentation, if you're writing code for someone else, like a teacher or a boss or teammates or a client, they'll likely want to be able to understand your code. Documentation comments are typically a large block of comments at the top of each file listing what's in each file, and also descriptions of each functional module - procedures (aka subroutines), functions, classes, etc.

...


But over top of all these suggestions is one overriding concern: CONSISTENCY!
You can take twelve source files that are all part of the same project, pick twelve different styles of formatting, all very nice and logical, and apply one style to each file....and out of every ten other programmers you show those twelve files to, at least nine of them will be p****'d off at the inconsistent formatting.
Every company typically has their own set of code-style guidelines, and the larger the company, the more pedantic the rules will be. For example, the rule that says every opening paren '(' must be followed by a single space, and every closing paren ')' is to be preceeded by a single space. Personally, I think that looks ugly, but were I to work for the company that follows that particular convention, I would adhere to it, because that's what the other coders I'm working with will expect to see. It's pointless to waste time reading code that looks funny because the style is unfamiliar, when what we really want to be doing is thinking about the ideas, algorithms, and structures that are involved.
And if you do find yourself in a position of being required to conform to a set of style rules, I think you'll find that what initially may seem ugly or just strange, will fade into the background once you get used to seeing it.