If anyone out there has any tips pertaining to the following subjects, please share with us!

1. Naming Conventions
1a. Variables
1b. Classes and Structures
1c. Functions
1d. File Naming
2. Commenting
2a. Where to place them?
2b. How to word them?
2c. How to make them noticeable?
2d. Length Limits
2e. General Style
3. Code Body Organization
3a. General Organizing tips
4. Anything else you would like to add

I ask because as I am moving into more complicated coding, I find that I really have no idea how to organize code or name things. I hope everyone will find this post helpful.


This post has been edited by Delta_Echo: 1 Jan, 2009 - 04:16 PM

The number 1 rule on coding standards is that there are no rules, except for those which your project leader/employer/client/etc impose on you. (If you're working on your own project then its down to whatever you feel comfortable with)

Don't fall into the trap of believing that any particular style is better than another. although I would personally suggest taking a good look at an implementation of the C++ standard library for ideas of how to keep everything organised and coding styles to aim for. Or if you plan to make heavy use of some other library, take a look at that (Keeping your own code consistent with the style used in library tools which you use the most is a good way to make your code look tidy IMO.)

Im not really looking for absolute rules. Im looking for advice on how to make the code more readable and easier to understand by other coders.

well, a coding standard I've adopted is to

capitalize the first letter of words in variable/class/function names
ex: MyVar;

before the beginning of a variable name, place a symbol for its type
ex: int nMyVar;

if the variable is part of a class namespace, global namespace, or is static put another symbol before the variable symbol with a underscore leading after it
ex: static int s_nMyVar;

and finally (a pet peeve of mine) brackets always get their own line (unless it's to increase readability, like a one line function that returns a member variable in a class declaration).
ex:
void MyFunc(void)
{
}

but of course, depending on who you work with or just your general preference, everything is changeable.

You could start instead by assuming that whoever is reading your code has little or no programming experience - to whom you could ask "what does this do?" and they'd be able to deduce approximately what something in your program is supposed to do just through the names you've used. (without worrying about meaningless technical details like syntax, data types, structures, etc.) The reason being that its easy to assume that other people will understand your code since they're "used to programming" but in reality its not so easy to understand exactly why someone has done something in a particular way. Usually the reason someone else is looking at your code is to understand what it does in general terms; Knowing exactly how it works is usually unimportant when reading through hundreds of lines to get an idea of what a program is doing. If you can put yourself in that other person's shoes, its clear that the last thing anyone wants to do is trace step-by-step just to be able to see the bigger picture.

With that in mind, spare your readers from dozens of lines of comments everywhere. a comment will generally stand out simply by its presence in your code. if a comment doesn't stand out, that may be an indication that you've got too many of them; on the other hand, if your code speaks for itself, comments which explain whats going on are unnecessary anyway - you can reserve them for anything which would otherwise be obscure or seemingly illogical at first glance, or for potential problems or future amendments. eg, a comment explaining why some seemingly weird hack has been used when there's an obviously better solution
Even that might be too much, depending on your preference for the size of your comments. Most big projects maintain some kind of change log/documentation where its easier to browse the gritty details of significant changes in one place. If you keep a comprehensive record of these changes, then comments in your code which relate to big/important changes can reduce down to a bookmark in your log, eg //see revision notes for v2.0.33.1 - section 3


When picking names think about the purpose of the objects and functions you're working with. Nouns generally make sense for objects (or iterators/pointers-to), since these are usually 'things' which exist somewhere in the system with a real-world angle on them. On the other hand, functions are blocks of code which do something so it generally makes sense to throw verbs into the mix when choosing their names. for example, the most immediate thought for a function name which records something to the project's central database might be "database()", but that's hardly descriptive of what happens when the function is called, it leaves no clues as to what you've just done to the database. adding a verb in there makes your intention clearer append_to_database( const FunkyWidget& ); - anyone reading that would easily guess that some or all of a FunkyWidget object is being added to a database (again, gritty details left aside since the main aim is to describe what's going on rather than precise details of 'how')



Another thought on coding style - you might decide that you're going to religiously follow a particular style of naming; commonly people choose certain letters to be capitalised, or separated by underscores, or distinct separate styles for functions, classes and objects; All of which is fine, it keeps everything looking neat and tidy. But remember that whichever style you choose will still most likely be lost on anyone who has to read or modify your code, because the only reason they're reading it is to understand what's going on; if you've imposed any meaning into your coding style, it'll almost certainly be lost in translation (or it'll add confusion if someone else comes along with their own 'meaningful' coding style and starts changing things)

Wow, thanks Bench and Master