I''m Programming now for quite some time and i''ve never used some code conventions like using the i prefix for int vars or f for float. Sometines when I''m looking into some code on the net i find conventions. Now my question, do I HAVE TO use code conventions and what do you use or find useful?? Are there some whitepapers on code conventions on the net?

There are plenty of papers (see Google) but you not likely to find anything that qualifies as standard .
It all depends on what you find useful, and once you make a particular choice its important to be consistant.

Having read similar discussions in the past, I''ve discovered that the general view is that prefixes regarding scope are what most people find useful, i.e.
g_ for globals
m_ for member
s_ for static

You can use others (e.g. i for int, f for float) but it can occasionally make names look ugly and in my opinion should be reserved for when it is important, for instance: it''s not that hard to find out the type of a local variable.
Personally, I also tend to use prefixes for windows stuff, like h for HANDLE, but I don''t usually prefix pointers although many people do (either p or p_).

well. I used to all the time with everything I did. but it just started getting, well, messy, and didn''t actually help. In the rare event you needed to know what type a variable was, you can just (in VS at least) hover the mouse over, and bang, it''s there.

I do, though, feel it''s definitly useful when dealing with huge inheritance strucures. The MFC standard of using m_ (etc) is very very useful as some mfc objects have enormouse lists of members/functions.

On the other hand, a short, and very discriptive name, imo, is the second most important thing. It helps with the most important thing, and thats clean code. The standards for Java, I believe, aid in making code feel cleaner quite a lot.. even simple things like all members being lower case first letter, I''ve moved to with C++, and somehow, it just feels much nicer. but thats just me.

(objects and members get lower case, classes and possibly statics get upper case... it just seems to feel right)

a quick rip,

shader->geometry.insert(entity->getModel());

just feels nicer than:

Shader->Geometry.Insert(Entity->GetModel());

I don''t know why. I guess it''s just me... (this happened to be the line I was editing last..)

I guess my point is don''t do what others say, take it in, sure, experiment, but do what feels right for you. Everyone absolutly MUST develop their own coding style to become a successful coder (IMO). That way they will feel most comfortable with what they do, and this will help learning considerably. The ultimate goal of a programmer, I feel, is to distiguish themselves from others. To be unique. There are more than enough ''production line'' programmers out there. If you get my drift (ie, I''m getting on to much bigger things here)


ohh well. way off topic. but still important I feel.

In college I used code conventions established by the teacher for commenting. In the corporate world it''s absolutely necessary when working on an enterprise level project.

Now even on my side projects I continue to utilize a coding convention to keep my projects clean and consistent. ( See: http://www.tronster.com/code/zelda/zelda.html )

Below I have posted an edited version of the contents of "code standards.txt" from my branch of the Open Source Zelda project. I recommend looking at the original text file, as from the paste I can see a lot of formmating has been loss.



. . . .: : :: :::[ Purpose ]::: :: : :. . .

Multiple developers may collaberate on the same project. To maintain uniformity among all modules, a single coding standard needs to be adherid to by all developers.



. . . .: : :: :::[ Formatting ]::: :: : :. . .

Tabs are set at 3 spaces. Tabs are non-destructive so the tab character is retained.

Coding lines should try to be 80 characters or less. While all modern text editors can handle lines of a much greater size, a reasonable fixed size allows for all code to be viewed in a debugging environment.

Methods should have at least 2 charage returns between their closing parentheses and the next method''s comment block.



. . . .: : :: :::[ Variables ]::: :: : :. . .

Variables should be descriptive and utilize Hungarian notation. The first letter of each word after the prefix is capitalized. The following tables shows the corresponding prefixes to be used:

Variable Prefix
------------ ------
bool b
class c
double d
DWORD dw
enum e
float f
Any global g_
handle h
int i
std::iterator itr
long l
std::map m
Any member m_
object o
pointer p
std::string s
char* sz
std::vector v
byte y


Constants, enumerations, and macros should be in all caps except for the prefix. If the define is more than one word long, an underscore should be used to separate the words. (IE: enum eSTATE_TYPE )


. . . .: : :: :::[ Methods ]::: :: : :. . .

Method names should start in lower-case letters, with each subsequent word being capitalized. Only system methods, or inter-process methods (IE: COM functions) should have the first letter capitalized.

Accessors should use "get", "set", or "is" as a prefix, depending on the accessor''s functionality. The name after the prefix should reflect variable being accessed.


. . . .: : :: :::[ Commenting ]::: :: : :. . .

Comments should use the C++ standard of two forward slashes where necessary. This will allow for blocks of code to easilly be commented out during a debugging process by wrapping the section in C standard comments.

Functions and method have a comment header before implementation. The header should describe the purpose, explain arguements passed in, report the pre and post conditions, and mention what is returned and/or thrown. A template is outlined below:


//////////////////////////////////////////////////////////////////////////////
//
// - The purpose of the method goes here.
// - Since this method is super complicated, it contains more than one line
// describing what it does.
// - Each line describes some other aspect of the method.
//
// ARGS: variableName, Description of the variable.
// variableName2, Notice the lineup of arguement names, and how the
// descriptions also line up.
//
// PRE: Post conditions can be a general statement, and/or a list of member
// variables which need to contain certain information.
//
// POST: Post conditions are just like pre-conditions.
//
// RETURN: A value, This is returned on success.
// Another value, Returned on failure.
//
// THROWS: A description of the type thrown.
//
//////////////////////////////////////////////////////////////////////////////


Any part of the above template may be ommitted if it is not pertinant to the method being described. (IE: If no arguments are passed in, then no need for a line with "ARGS:"

When a developer wishes to mark a section of code, they do so by starting a comment with three question marks followed by their initials without any spaces. (IE: // ???TMH - Why the heck does this throw? ) Dead code should be marked in this manner or removed before check-in to version control.

When it comes to comments in code, I have mixed feelings...

All code should not need a single comment to be understandable. If it isn''t this way, it''s likly it''s being written badly. There are obviously some exceptions, but very few. Obviously there should still be ''pointer'' comments just reinforcing whats going on.

The next point is in a major project, with good structuring, 1 programmer should not have to wade into another programmers code often, if at all. They should be responcible for the code they have to maintain. While this isn''t a reason to not have comments, it is, I feel, a reason to not have enormous block comments discribing every possible characteristic of a function, and comes back to the fact that code should be understandable by names, and if a function does need a large comment block to discribe what it actually does, then maybe it needs renaming, or it is doing far too much.

I also believe having a prefixed name (with the exception of m_ in large apps) is only going to make the code harder to read. The code should flow, with .''s or ->''s being equivilent to spaces... It should be as close to a sentence as possible, just with only verbs. The type of a member should be obvious by it''s name alone.

vertexBuffer is discriptive, and obviously a pointer to an array of verticies... pv3_VB isn''t...

lastly.. I can say in my time I''ve looked through some absolutly utterly shocking code... odly, most has been while at university, which people learn off... The biggest sins I find in this sort of code was mainly four things...

massive block comments where they shouldn''t be... often explaining things that really did not need to be explained.

comenting almost every line, on the line. Comments should always come before the code they are explaining. They should be short and sweet. Putting them a few tabs after the line is both ugly, and hard to read. And a nightmare to edit without it all going to custard.

Not grouping similar operations. In this case, I mean having a single line between each actual line of code (or none). No matter the code. This is a hard one to explain...

And finally, over trying to make the code ''efficient''... My biggest pet hate is people putting the opening brace on the same line as the if block, function name, or what not. This breaks up code badly. Things like this.


As a final point, but OT. A good class structure, and MOST importantly, a good VISUAL structure for editing are CRUCIAL. Editing classes by file is, imo, not good... Having your classes arranged so they are grouped, and in a tree stucture, can GREATLY simplify the complexity of your application.

eg, in my project, I could have all 3 odd pages of classes in a straight list. But I don''t. they are grouped in Game, Engine, then things like rendering, objects, common, etc... This boosts efficiency an enormous amount.

<-- smile :-)