Hi,

I agree with Peter, coding convention helps in understanding the code, make it more readable…

Whatever convention is adopted , it needs to be consistant trhough the whole document. So it is not a good idea to allow developer to use their own coding convention within a single project.

Here is a good reference:

http://www.possibility.com/Cpp/CppCodingStandard.html

I would say however that there is not enough comments in the overall calitko code.

I think each functions should have a comment explaining what the function does and what are their in and out paramaters. Even if you try to find obvious  and self-explanatory name, a comment will explain the things better.

regards

seb

Peter Dimov wrote:

Hello everybody,

I thought it would be nice to open a discussion by presenting my view of coding styles/conventions for Calitko project. Most of you maybe already know that there is a section in the documentation called Coding Conventions. It is still quite short, not really detailed and not at all complete. I’ll try to extend it stepwise for each new source code release. It anybody is interested in helping me finish it faster, please contact me.

There is no need to go into the details of why coding styles/conventions are good. I expect that everybody is already familiar with the general idea. Still, in a nutshell, conventions prescribe some good practices or idioms, which if applied would improve code quality or reduce probability of making errors. Another kind of styles are totally esthetic in nature, like indentation for example. Their sole purpose is to make code as readable as possible and more beautiful, if possible.

Every human being, consciously or not, loves to create good things. Calitko is predetermined to be extremely good because we develop it with very high quality standards in mind! Not only the GUI, but also the software architecture, design and source code will be beautiful and a pleasure to look at from both esthetic and technical point of view. This way of doing things further contributes to the distinctiveness of Calitko.

Some people have already noticed that in the source code of Calitko some things are done differently than the way they are most commonly done and especially in our combination. I find this property of the source code nice because it contributes to creating a Calitko identity. For example:

class MyClass { public:             MyClass();             MyClass (MyClass &);      int     value() const;     void    setValue (int); };

You see how the constructors and member function names are aligned. You’ll probably also notice the space between the function name and bracket, when the function has parameters, and its absence otherwise. These (and other similar) stuff is nothing I claim to have invented myself. I’ve seen different stuff over the years, some I’ve liked and applied in Calitko. I do not want to insist the Calitko style is better than other style. It’s all a matter of taste and I expect that not everybody will have the same taste, so I tried to reflect on that fact.

I was wandering whether it would be nice to allow each developer to use their own style when updating existing or writing new code, as that would contribute to a very special and unique coloring of the source. My concern in this case is that too much, or too random, coloring would lead to a very patched-up looking source code, which does not sound to me like a too desirable property.

I was also thinking about the possibility to let developers use whatever style they want when coding and have a small program or script convert their changes to “canonical” form. This script can be used by the developers to canonize source code before generating a patch, or to canonize the patch, or the complete code of Calitko could be canonized before each official release. I know we already have some Perl experts on board and I guess writing a Perl script to do the canonization would not be a big deal. Am I right?

I hope this post will give a pulse for further posts on the topic.

Regards,

Peter