Coding Style | neraliu's blog

185月/090

c/c++ coding standard – is it still in the college?

c programming language

no matter what! C is one of the most popular programming language in the world, it is used widely in different kind of computer systems, you can hardly find the system with no C compilers (surely, there is, need to do a little research on it, but it does not affect my popular claims here). referring back to my previous article - "be a good developer - the first step is to consider the coding standard/style", i do think C can be the starting point in considering coding standard because of its popularity, by the way, most of the thing describing below are actually C++.

why standards? this is all "maintainability of the source codes" about, and thus i know there are some long fighting arguments on standardization, this is not my scope in this article, anyway, i do agree coding standard is actually "the art". :p

name matters?

the name - the first place to start with, when you are working on the C/C++ programming, i think you should start think of the naming convention of all below.

library names / namespace

it is highly recommended to consider before the coding gets started, as careful thinking on the library name / name space resolves the name conflicts in the future.

interface / class names

with the object oriented programming in mind, the class name most of the time should be a "noun" to represent the object itself and below is some general idea.

it is recommended to use the upper case as the word separators and smaller case for the rest, like UserProfile etc.
it is recommended to have the prefix "I" in the interface names.

class attribute names

same as the interface / class name, it is supposed to be the "noun" in describing the attributes of the class.

it is recommended to use the upper case as the word separators and smaller case for the rest.
it is recommended to have a prefix like "m" in all the variable names, like UserProfile->mName etc.
for public, protected and private variable names in the class, it is recommended to have convention to identify them, like private variable prefixing with "_m", while public one prefixing with "m" only.

method and function names

all the time, it is supposed to the "action" on the "noun" in the object oriented programming semantic, so making the name understandable is the core of the design of the name.

it is recommended to use the upper case as the word separators and smaller case for the rest, like UserProfile->Register() etc, in which everybody understand "it is used for register the user profile".

variable names

it is recommended to use the upper case as the word separators and smaller case for the rest, like NameCnt etc

variable names on the stack

it is recommended to use all lower case with the "_" as the word separator.

pointer variables

it is recommended to have a prefix like "p" in the variable names.

reference variables and function returning references

it is recommended to have a prefix like "r" in the variable names and function with returning references.

global variables

it is recommended to have a prefix like "g" in the variable names.

global constants

it is recommended to use upper case for all characters with "_" as the separator.

static variables

it is recommended to have a prefix like "s" in the variable names.

type names

it is recommended to have the "Type" postfix for all the typedef in the code, like UserType etc.

enum names

it is recommended to use upper case for all characters with "_" as the word separator.

#define and macro names

it is recommended to use upper case for all characters with "_" as the word separator.

the comment

before we go further, there is one thing need to be considered in the source code file, it is the thing most people miss to key into the source code file, it is the "comment". but the question is what should we comment on the code? and how deep should we go for it? the idea is simple, you should dive from the top to the bottom when doing the comment on the code as long as you found in it enough to go.

project - it is the place what it the goal of the project, but most of the time, it should be placed in the README file.
libraries / subsystems - it is what the libraries / subsystems intend to do.
classes / interfaces - what is your classes / interfaces about?
methods / functions - what is your methods / functions intend to do? though the name convention should put some light on it.
methods / functions argument - again the name conversion should put some light on it too.
variables name - state the purpose of what is going to hold
logic flow - this is not the bottom one, but specially to comment it as long as your logic is not easy for other people to understand, u genius.

and for the format of the comment style, simple enough, just try to align with some source code documentation generator, like doxygen, is fine enough for what you need. as you can have the documentation generation with automation.

the header files

this is important, most of the time, the header file is the interface to the outside world, letting other developers to understand what interface your library provided. it is highly recommended to align with the whole team in using the "same naming convention" and the "class layout sequence if OOP" of it, so as to standardize your interface to the outside world.

using file header guard

using the file header guard to protect the redeclaration of the header files.

// #ifndef filename_h
// #define filename_h
// #endif

the file extension

we just simply stick to the common standard, with *.h as the header file, *.c for the C source code while *.cpp for the C++ source code files.

best practices on do, don't and be careful

do use the smart pointer all the time

the absolute reason is it makes "less bug" and have the code looks clean if you use it correctly. if you use nicely, you can hardly see the "*" in the code, wonderful! what the nice attribute of mart pointer is of "auto initialization" and "auto clean up", "solving the dangling pointer issues", and "having exception handling nicely".

do use the "const"

sometimes, you are not going to alter the value of throughout the run time of the code, it is highly recommended to use the "const" for the sake of avoiding mistake. and for the function argument passing, it is recommended to pass by reference with the const if applicable, this helps to make sure thing not alterable inside the function. however, one thing need to be careful is the confusing syntax of const in the code, somehow, it is hardly to remember it.

function_name( object_name const & variable_name);

do use the pass / return by reference all the time

the most good thing of using reference is it always point to something exist, for example, if you declare the "int& i;" in the code, the compiler will complain the variable i is declared as reference but not initialized, and this is not the pointer can offer, always leading to memory management issue in the code.

do implement the copy constructor and assignment operator

it makes the "deep" copy of the object rather the bit-wise copy of the object, the copy constructors and assignment operators make the correct copy operations on the dynamic element, like pointers.

don't use the magic number

it is highly not recommended as it makes the code unreadable after a few week time, even though it is written by you.

don't use the type casting, except you know the rationale of polymorphism

avoid to use the type casting, as it makes the code difficult to be debug most of the time.

don't use the macro, especially the NULL macro

always use the zero, but never use the NULL in C++, as there is no guarantee in the defined constant of NULL is compatible with the pointer of different types.

don't pollute the global namespace, define your own namespace

be careful about the destructor when there is polymorphism

pay attention to the destructor when you are having the polymorphism in your code, otherwise the wrong destructor is called leading to the memory leak for some dynamic elements, you may need to consider to have the virtual destructor somehow.

miscellaneous on code appearance

braces policy

it is recommended to use the traditional unix policy having the initial braces at the same line of the control statement or
it is recommended to have the initial braces after the new line of the control statement.

indentations/tabs/space policy

code should be indent with spaces as it makes the code much more readable, there is no rules on how much spaces should be indented as long as everybody agrees. but once you find there is too much level of indentation, it is time to find about to re-factor your code.

references - http://www.possibility.com/Cpp/CppCodingStandard.html
references - http://www.idleloop.com/hungarian/index.html
references - http://www.cplusplus.com/doc/tutorial/

存檔在：科技, 電腦沒有回應

155月/090

be a good developer – the first step is to consider the coding standard/style

working in the multinational company, who you work from day to day is the people from all over the world - the folks from amercian, indian, taiwanee, korean etc. yes. it is multinational and versatile enough to be your life. for communicating with different people, language is what the vehicle, either in spoken or written. being trained up as an engineer, written is of no problem, but it is not very strong at listening some how, as we are all not natvie speaker all the time, not even me, also the people who work with u. lucky me, my mother spent half her salary in my childhood to put me in kindergardens, primary and secondary school with english as the learning medium, making me still manage to go through the day.

faint me, what are you talking about in this artcile? it is about the coding standard thing in the computer world, sure, what i wanna to make it analog with the spoken language to computer language is the "accent" to "coding standard", this is what make you feel uncomfortable, the more uncomfortable, the more difficult to get it through. I was taught with "british style" english, i am good at listening to british people, american is fine if it is not too fast, but it is not true for indian as i need some time to warm up. it is also true for the "coding style", most developers are not uncomfortable with other people's work, as long as, they can trust the piece of code as the library behind the scene. this is good and of no problem for being as the third party support, but it is not for the team, especially we are of the global team. i do believe the missing glue is the "code standard" to make you feel better.

when u are defining the code standard of the project, the first thing come to your mind is why you need it? making you feel better? part of it, the exact answer to me is simple, the project should be continued no matter what, as long as there is a need and this come up with the term of "maintainability of the piece of code base". sure, making the "code standard" is the first step and how to enforce and verify is definitely the key factor to make it success, anyway, out of scope in this topic.

so what is the coding standard? to me, it is kind of a very board scope of it, ranging from the tiny thing of "how much space as the indentation in the code?", to some large scope of "how to add a new peice of code to the package to be built?" etc. it starts converging to some common practices of the team development on the way.

without get lost in the discussion, i am good to draw the circle to make our thing solid can be discussed. no matter what computer languages are you talking about, there are two important things should be come over when you are going to have a code base managable

down to the ground - anything you key in the source code files
a little life off - the file layout of your source codes.

in this article, i am not going to drill down to every details of the above lines as you will find it is of different considerations when you are working on different projects with different languages, like web applications, desktop applications etc. but i would spot the lights to all the items that should be considered when come across your own project in the hands.

anything you key in the source code files

the indentation style - this is the thing to help in identify the block of code segment, but there is no such thing of the better indentation. as long as it can help to identify the code segment, it serves the purpose, however, some of developers feel much comfortable if your team can align with this little details, like using two spaces as the indentation through the code.
the commenting style - lack of documentation in the source code is the thing happening n the industry, and having comment in the source code can be part of the official documentation of your work (you can refer to another article of me on describing how to document your work), but most of the times, the scheduled time is consumed by another coming projects on the road, this is the reality sometimes. anyway, so aligning commenting style is definitely the MUST in the consideration. in the web, there are a quite a few of source code documentation generator tools (like doxygen etc) to help, the tools you chosen, the comment style your team stick to.
the variables naming conversion - this category falls into the way of how the team name the variables in the code, and why this matters? in the traditional programming, it is the global / local variables you come across, and in the object orientated programming, there is no need to mention the public, protected to private you are going to concern. those variable types is one of the reason you are going to come up with the variables naming conversion in the consideration.
the functions / methods naming conversion - same as the variable name conversion, this serves as the purpose of letting different developers in the team to understand the types of the functions / methods be, for example, the getValue()/setValue() is one of the typical examples in the OOP regime you encounter most of the time.
the code appearance - curly braces, spaces, tabs, vertical alignment and more... - if you consider as "whatever you key into the source code" is part of the consideration, you find that even a little space matters, however, i would claim this is just a matter of making you feel "comfortable" when you are being assigned with a code base from different people (this is not true for the coding style of curly brackets, it matters when you are going to debug the code, as the experienced developers, you know what i mean), anyway, sometimes it matters as a team somehow.

the file layout of your source codes

the next thing you are going to consider is the place where you code and related file going to be stored. surely, different kind of applications have different files going to consider, for example, source files, class files, and resource files are going to be considered, however, in general, the files below are the thing we need to consider most of the time.

the file location / structure of your source codes
the file location / structure of the external libraries
the file location / structure of your configuration files
the file location / structure of your resources bundle, like i18n stuff etc.
the file location / structure of your software build
the file location / structure of your visual files, like image, video etc.

time to go, talk next time, i am going to dive down to more details on the mentioned about with different application development and the thing comes next is the "the coding standard of php web development".