| We hope you enjoy your visit. You're currently viewing the Ultimate 3D Community as a guest. This means that you can only read posts, but can not create posts or topics by yourself. To be able to post you need to register. Then you can participate in the community active and use many member-only features such as customizing your profile, sending personal messages, and voting in polls. Registration is simple, fast, and completely free. Join our community! If you are already a member please log in to your account to access all of our features: |
| Good coding style and naming conventions; The earlier you get consistent the bette | |
|---|---|
| Tweet Topic Started: Jul 13 2008, 03:15 PM (736 Views) | |
| Dr. Best | Jul 13 2008, 03:15 PM Post #1 |
|
Administrator
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]()
|
Hi everybody, this is my first tutorial for the new forums and the reason why it is the first one simply is that you should get to read something like this as early as possible. Mostly it is meant to avoid that you make used to bad habits. It is aimed towards novices. Today I am going to talk about good coding style and about naming conventions. This tutorial applies to every programming language, but in particular it does apply to C++ and C#. So lets get started. What are naming conventions and why are they important? If you are programming in C++ you will need many names for many different things: Variables, functions, structures, classes, enumerations, macros and constants specified through define are the most important ones. The name can be any alpha numerical string and it can include underscores ( _ ) . Naming conventions are rules, which are used to chose the names. To demonstrate their importance here comes a little example in which no clear naming conventions are used:
So what is bad about this piece of code? The answer is simple. It is not consistent with its naming conventions. Of course the example is a bit exaggerated, but it shows the problem quite well. Some variable names start with lower case letters and have their words separated through underscores, some start with lower case letters, but have their words "separated" through capital letters and PrintVals starts with a capital letter and separates the words through capital letters. bPrintIndices does have the prefix b, which implies that it is boolean, withNums does not have a prefix like this although it is boolean, too. Some names are abbreviated (like val instead of value) some are not. The names are random and do not match to any set of rules. This makes the code hard to read, since you have to look out for different markers for new words and variable beginnings all the time and it makes it hard to write since such random variable names are hard to remember. This is why naming conventions are important. Naming conventions are rules in the form of "If you have this, call it like that.". It does not make a big difference what naming convention you are using, but it is important that you are using the same convention everywhere. If you do so you will find it significantly easier to remember the names you gave to particular things, because you always know what form they must have. And it also makes it easier to read your code, because with a good naming convention the name already tells a lot about the object behind this name. An exemplary naming convention: At the beginning it can take a while to find a naming convention you like. Though you should find one as fast as possible, because as long as you have not found one your names will be inconsistent. To help you in getting an idea of how a naming convention may look here is a description of the one I am using. I will formulate it as a list of rules:
As I already said it is more important that you decide for some naming convention and use it everywhere. It does not have to be this one. Though I have made good experiences with this naming convention. Even in code, which I wrote month ago I often can guess variable names correctly. This eases the development significantly. Once you have decided for a naming convention (and you should do this as early as possible, but with bethought) you should use it also for variables, which use types from some external APIs. If they do have names, which do not match to your naming convention in some tutorials this does not mean that they can not have names, which match your naming convention in your code. To show you how significantly a naming convention can increase the readability of code here is the code above with consistent naming:
It does look significantly better now, doesn't it? Comments in code: There is a neat little quote, which is always good to start talking about comments: "Good programmers do not comment their code. If it was hard to write it should be hard to read.". Notice how the sarcasm pours out of this sentence. There are many good reasons why good programmers do have lots of comments in their code. I want to list some of them here:
So how do you create good comments? The second one of the points above already included the most important trick. Before you write a piece of code you write what this piece of code should do in a comment. This way the comment functions as a mini to do. You could see it as an order to yourself: "Write a piece of code, which does this now.". This method of commenting code is especially important for code that implements functions. But a C++ project usually has more than that. There are function declarations, variable declarations, class definitions, etc. These should be commented as well. These comments are the comments, which will be important for documenting your project (and they are even more important, if you do not plan to document your project properly). For a function declaration the comment should say what the function does and what has to be passed for its parameters to reach that it will work properly. Again the comment can function as a mini to do here. For a variable declaration the comment should say what information this variable saves. For a class the comment should say what the purpose of this class is. In general comments for declarations should always describe the purpose of the declared object. Now I have been saying why you should comment your code and how you can write good comments. What is still missing are some words on the form of comments. I have noticed that C++/C# beginners (I did so, too) often use strange constructs to highlight comments. Like this:
What I am talking about are the many asterisks (*). This habit probably results from constructs like this, which have been read in tutorials and code by others. I personally absolutely do not like such constructs. It takes quite a lot of time to write them, having them makes it more complicated to change comments and they do not fulfill any good purpose. Comments already salience due to their green color (which they have in almost every IDE by default). Comments, which stand at the beginning of a function or a class definition can be recognized without such constructs, since they are not indented. The comments simply do not need to be highlighted like this. You should better use more empty lines instead. They can highlight comments just as well. Other than that comments should use full sentences in my opinion (although you may have a different opinion in this point) and they should be specific enough. A bad example would be "saves a model", while a good one would be "This function saves a model to a file". I made used to ending comments with a dot exceptionally, if they contain multiple sentences and I find that quite practical. Additionally comments should always have their own lines of code in my opinion. Here is a bad example followed by a good one.
The good example is almost a bit exaggerated, but I hope you get the point. One last rule is that you should start a new line for your comments, if they are too long to match into the editor window otherwise. If you follow all these rules your code will be a lot easier to read and to use, since it is always easy to find out what a function or a piece of code does thanks to the comments. Additionally you can write it easier, since you enforce yourself to make up a clear idea of what you want to code next. Finally to give another good example here is the example code above again, but this time with good comments.
Other aspects of good coding style Last but not least there are also several other aspects of good coding style. First of all I want to say that you should always indent your code properly. Most IDEs do this automatically for you, so it is not much work anyway. C++ and C# compilers do not distinguish between different white spaces (meaning that it does not matter for the compiler whether you indent or not), but it simply makes the code easier to read. Another aspect of good coding style is how you place your brackets. Especially for curly brackets this is important. I recommend that you either place every curly bracket in its own line, or that you place opening curly brackets at the end of lines and closing curly brackets in their own lines (this is what I am doing as you can see in the code above). Doing so makes it easier to recognize where particular scopes start or end. Other than that I recommend that you use curly brackets after every if, while or for statement, even if they will contain just a single statement. This makes it easier to read the code, it makes it more clear, avoids mistakes and makes it easier to add code to the scopes of the statements. You should also use enough spaces and new lines in your code. Do not try to keep it compact by not doing so. When I was a beginner I used to have extremely compact code. It was hard to read and did not look good. You do not need to save space, a bit of scrolling does not take long and IDEs offer many tools to jump to particular declarations or definitions in code. So simply take the place you need to lead the eye of the reader to the parts that matter. The code above can be considered a good example regarding these aspects of coding style. For this reason I will not give another good example, but just another bad example. So this is how the function PrintValues(...) would look in bad coding style (regarding the aspects I have talked about recently):
Languages in code One last thing that needs to be mentioned in a tutorial about good coding style is how language should be used (I am not talking about programming languages, but about "speech languages"). Language is relevant for two things in source code: The naming of variables, functions, classes and other objects and for comments. I recommend that you always use English for both. English is a very good language for programming for the following reasons:
.Final words This tutorial has become a lot longer than I had expected. I have seen code with inconsistent style and bad names very often and I used to think something like "Why can't this guy just code a bit cleaner.". Having written that much about this topic now I realize that a good coding style is not as self-evident as I had thought. Developing your own coding style can take a while, but it is very important. Without a consistent coding style your work is less efficient, more fault-prone, harder to reuse and harder to maintain. For this reason I hope that I have been able to help you in doing so. Many things I have talked about are a matter of taste, but for most of them I said that they are one. The three things, which are not a matter of taste or opinion are that names should be chosen in a consistent and descriptive way, that precise comments are helpful for reading and writing and that code should be indented and not too compact. So for your own good, keep these points in mind. With friendly regards, Dr. Best P.S.: I did not check the example code for mistakes using a compiler, since it is more about how it looks than about how it works anyway. |
![]() |
|
| skarik | Jul 13 2008, 06:12 PM Post #2 |
|
kitten eating scum
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]()
|
Huzzah for readability! (Nice tut.) |
| Blog|EHS | |
![]() |
|
| Rixeno | Jul 14 2008, 01:41 AM Post #3 |
![]()
Teo-Carliss
![]() ![]() ![]() ![]() ![]() ![]() ![]()
|
Wow, that was long, but very useful, especially when it would come to new programmers in any language... My GML coding style was close to that when it came to description, indenting and consistency (a little)... I liked the tips on naming the variables/functions/classes/arrays/etc. and I'll try to write like that.
|
|
Report spam the nanosecond you see it. Ninjas are everywhere, for all you know there are eleven behind you right now, including me... | |
![]() |
|
| Dr. Best | Jul 14 2008, 10:32 PM Post #4 |
|
Administrator
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]()
|
Thanks for the positive feedback. I just added in another part. It was planned from the beginning, but I simply forgot about it, while writing the tutorial. The new part is the last but one and it explains why it is best to code and comment in English. |
![]() |
|
| « Previous Topic · Tutorials · Next Topic » |





![]](http://z1.ifrm.com/static/1/pip_r.png)
. While you are writing a piece of code you usually know what it does. But your software changes over time and usually code needs to be changed some day. Then you will need to be able to understand it again. Comments are very helpful in this. And they ease the use of the code since they can say how particular functions, classes, structures or enumerations should be used.




9:02 PM Jul 11