← Back to team overview

kicad-developers team mailing list archive

Re: Why ALL capital letters for classes and typedefs


Le 22/06/2012 18:44, jean-pierre charras a écrit :
Le 22/06/2012 10:16, Lorenzo Marcantonio a écrit :
On Fri, Jun 22, 2012 at 01:02:18AM -0700, Alexander Lunev wrote:
The KiCad coding style policy contains the requirement: "Class, typedef, enum, name space, and macro names should be comprised
of all capital letters."
My question is why should CLASSES and TYPEDEFs be comprised of ALL capital letters? What is the reason for that?

The most common convention that I have ever seen before sounds like:
"A class name should begin with a capital letter and be written in mixed case (e.g., String). If a class name consists of more
than one word, each word should begin with a capital letter (e.g., StringBuffer). If a class name, or one of the words of a
class name, is an acronym, the acronym can be written in all capital letters (e.g., URL, HTMLParser)."

Well that's not the strangest coding convention in kicad :P just ask our
tyrannical leaders, they'll just say "they can't read them otherwise".

Oh well, I've no issues with that...

First of all KiCad coding style is not a whim of developers,
and it is not intended to be the best rules never seen to write code.

It is a set of rules to keep KiCad sources easy to read and maintain.
The first requirement is all sources should have the same look.

Therefore KiCad coding style define a set of rules to do that.

Class, enum ... names must have a style (the same in all files).
You can use:
- names starting with a capital letter and written in mixed case.
- names starting always by a given prefix like "ki" or "Ki" or "KI" for kicad (like in wxWidgets).
- names in capital letters only

and much more.

By a decision must be taken: it was "names in capital letters only"

The advantage is class names area easy to identify when reading a file,
because other words are not capitalized.

Some others tricks are used to easily identify variables:
argument variables have a name starting by 'a' (like aCount, aValue)
local variables have the first letter never capitalized ( countmax or countMax)
global variables have the first letter always capitalized ( Countmax or CountMax)
class members variables have a name starting by m_ ( m_count, m_Count )
    public members variables have the first letter after m_ always capitalized  (m_Count)
    public members variables have the first letter after m_ always not capitalized  (m_count)
    or just written like local variables (count) .
    ( I prefer the name m_count to count )

See KiCad coding style for many other rules.

Developers *know* other rules are widely used, but to write "KiCad coding style"
decisions must be taken.

Rules in "KiCad coding style" are not always rules used by some contributors when they are not working on KiCad,
but I am thinking KiCad coding style should be acceptable by everybody.

Strange coding convention is usually coding conventions used by "others"
Therefore there is a *lot* of "Strange coding conventions"
(usually coding conventions that do not match *my* coding convention)

At last, the best answer to
"Why should CLASSES and TYPEDEFs be comprised of ALL capital letters"
could by: why not?

Thanks to developers who carefully read the KiCad coding style rules.
I am sure you could find some good ideas inside.

I forgot:

1 - The easier way to format files according to KiCad coding style is to use Uncrustify,
a free tool to format source files (in a lot of languages).
the config file for Kicad is kicad/uncrustify.cfg
I am using it a lot.

2 - Pay a *particular attention* to KiCad coding style, chapter 3 and mainly 3.2,
(and headers in kicad sources to know what is expected in kicad):
Sources *must* be commented.
For me, this is the more important topic of KiCad coding style:
without good and well designed comments, contributions are useless.

Jean-Pierre CHARRAS