GENERAL: Programming Code Guidelines & Styles

Question

I know that each programming language has certain guideline and styles. My question is about two languages that I write code in, that isn't very popular or documented.

I know this topic is very broad, and everyone has their own unique way of doing things. What I would like is to hear advantage, disadvantages to certain styles.

In order to explore this question, imagine you are writing your own programming language, based on what you've experienced in the past, what is the best way of going about things?

Remember, there may be ups and downs based on specific languages, so think if this language didn't matter. I am still fresh to programming, so I want to get the best habits of making my code readable and easy to follow.

There are so many topics to talk about, Ill get run by the basics:

Global Variables
Should they start with _ and be all capitalized?

Local Variables
Should they end with _ and be always be lowercased?

Variable Names
If I am defining something like an employee's hourly wage, should it be EmployeeHourlyWage, Employee_Hourly_Wage?

Variable Types
Should you include the type of variable it is in the name, for example if I define $Hours and it has stored to it an integer, should I name it $Hour_INT so that I know when referring to it what type it is? Who knows, I might have an $Hours_FLOAT

Curly Brackets
Should the brackets line up with themselves such, the words, or what? Which one of these are best, preferred, most readable?

IF ($Test) {
 //code
} ELSE {
 //code
}

IF ($Test)
{
 //code
} ELSE {
 //code
}

IF ($Test)
{
 //code
}
ELSE
{
 //code
}

Alignment
I am constantly lining up variables and their values so I have an idea where what goes where. Is this bad practice:

// Assuming GUI(TOP, LEFT, HEIGHT, WIDTH)

GUI( 23    , 44   , 245   , 2323    )
GUI( 232   , 4332 , 22    , 6576    )
GUI( 21    , 4    , 1     , 5       )
GUI( 34235 , 13   , 31237 , 4564665 )

// OR

GUI(23,44,245,2323)
GUI(232,4332,22,6576)
GUI(21,4,1,5)
GUI(34235,13,31237,4564665)

Indenting
Why do some coders use spaces instead of tabs? is there a amount of spaces that is recommended?

---

I understand all of these could be questions in their own. I am not sure where to get all this knowledge from? I could spend hours just asking you what is the best method. I am sure the more college courses I take, the more it will be hit on (or not).

It would be awesome if there was a site where programmers of all kinds talk/discuss/rate/wiki the best methods and practices of programming. Would also help serve future languages to better suit the needs. I guess if there was one right way, there wouldn't be so many variations in languages and style. I just would like to know your arguments and whats mainstream so my coworkers know what I am coding.

Answer 1

I think this is all a matter of personal taste.

Use the coding-style you feel conformtable with, whenever you can.

When you work on a team, try to all use the same coding-convention unless you want the code to be a mess.

And if you really don't know what convention to choose, choose a popular one: whether it is google's, Richard Stallman's or whoever's don't matter: just try to be consistent.

Mine evolved during the past few years and probably so will yours.

Here is my advice: you should focus on writing good and maintenable code first; tools exist to fix/change coding-styles.

Answer 2

These are all really subjective issues - people mostly disagree about these sorts of things, and to be honest it really doesn't matter that much! :-)

I'd say that the only thing that you can actually do wrong is to be inconsistent about whatever pattern you do use.

Answer 3

Have a common standard within your team and follow within your team consistently. Make sure that it is readable and understandable. After all the code for us humans to read.. :) Computers use object code anyway..

Follow those and have it documented.

It's enough if the Code is understandable.

If a new joiner can able to understand your code based on the Document you provided, then you are good at it.

I think it's just more than enough. It's my opinion though.. :)

Answer 4

For Java, most people seem to follow a style that's based on the defacto standard described in this document: Code Conventions for the Java Programming Language.

For variable names, that means use camel case, starting with a lower-case letter, for example: employeeHourlyWage. For static final values (constants), use all-uppercase and separate words by underscores, for example: EMPLOYEE_HOURLY_WAGE.

Don't start global variables with an underscore, don't end local variables with an underscore. Do not include some abbreviation of the variable type in the name of the variable (doing that is called Hungarian notation).

I prefer the following bracket style:

if (condition) {
    // do something
}
else {
    // do something else
}

Indenting with 4 spaces is most common in Java.

I agree with the other answers that consistency is more important than what particular style you choose. For Java, it's a good idea to pick a style based on the above-mentioned document, as that will be what most Java coders will expect, and the style that's used in the standard Java library and almost all open source Java libraries.

For C, the GNU coding standards are probably a good thing to look at.

Answer 5

Here are my thoughts. Others will disagree, but as I think it has been pointed out, the main thing is to be consistent.

Global variables: I have no special naming convention for them, mainly because I avoid using them as much as possible. In my C code, I do use variables with static scope i.e. visible in the compilation unit, but again I don't bother with any naming convention.

I tend to use the Java capitalisation convention i.e. instances, variables, members etc use camelCase with a lower case first letter. Classes, structs, typedef types use CamelCase with a capitalised first letter.

I avoid prefixes and suffixes of any kind. In fact, I loathe prefixes ever since I had to debug a C++ class which had about twenty instance variables, all of which began "m_lpsz" and were thus almost impossible to distinguish. I know Charles Simonyi is a genius, but he should be shot for Hungarian notation.

Prefixes and suffixes that give you information about a variable are also unmaintainable. You need to be able to change the type of a variable or the scope of a variable without having to do a global search and replace on its name because you can guarantee that one day somebody in a rush will do the one without the other and then the variable is lying about what it is.

Braces: I think that if K&R 1st edition had not used the K&R brace style and somebody tried to introduce it now, we would regard them as insane. I can just about see a justification for it when terminals had 25 lines (or were actually teletypes with printed output), but there's no reason to use that style anymore. I find it makes the code look dense and cluttered.

Alignment: your first example is easier to read. What do you think the answer is?

Spaces, tabs: I use tabs because it's quicker to type 1 tab than 4 spaces. I think I'm probably in the wrong on this one, but on the other hand, with code reformatters, the issues that tabs cause (some people set the tab stops every four, some every 8 spaces) can be rectified quickly.

Answer 6

I think the best you can do is try out a few well documented coding style, choose what you like the most then use it consistently.
There are a lot of styles: http://en.wikipedia.org/wiki/Indent_style

Maybe K&R based styles the most popular, so would't be a bad idea to try one of those.
My personal choice is KNF.