[Ctags-devel] Initial ground rules for ctags developers

[Darren H. <dhi...@us...>]

As recommended in the SourceForge guidelines, I should set some ground rules 
for developers being accepted into this project.

So far, all those who have expressed a desire to maintain some part of ctags 
have expressed an interest only in maintaining one or more language parsers.

Therefore, I will establish the following ground rules for all developers (per 
the SourceForge definition, which is different from a project administrator). 
Everything below is open to discussion. I want to keep ctags development 
running smoothly and in a friendly and courteous manner.

1.  Responsibility and restrictions

You will be expected to restrict your changes to the specific language 
parser(s) for which you are responsible, and which are each contained in a 
single file. I request that any other changes to ctags be coordinated with, 
or arranged by, me.

2.  Coordination

For parsers maintained by more than one developer (especially C-style parsers, 
which are all handled by c.c), I expect the maintainers to coordinate their 
plans and changes amongst themselves.

3.  Testing

I expect that all parses be supported by one or more test files located in the 
Test directory of the repository. Ideally, this test file will contain at 
least one of every type of tag the parser can recognize. More will be said 
about this later.

4.  Coding style

Please abide by the general coding style used throughout ctags and defined by 
the .indent.pro file contained in the repository (a configuration file for 
the GNU indent program). I accept certain variations from the style resulting 
from running indent over the code, as it is impossible to fully configure it 
the way that I like. However, any variations should be for the purpose of 
making that particular piece of code clearer to the reader.

Examples of variations you will see in the code are switch() statements 
arranged in a table format, as well as certain comments.

One thing, in particular, that I would like to see observed is that code is 
indented using tabs for the initial indent. While I like using a tab setting 
of 4, it is my intent that the code layout be independent of the tab setting, 
thus allowing anyone to use whatever tabe setting they prefer. In order for 
this goal to be achieved, it is necessary that any tabular arrangements you 
make to align code (such as the switch statements referred to above), use 
spaces to achieve the alignment beyond the tab-based initial indent. For 
examples of this, please see the definition for KeywordTable[] at line 357 of 
c.c and the switch statement in the processFieldsOption() function, beginning 
at line 843 of options.c.

Please do not try to line up local variable names or continued lines (broken 
because of line length), as these become dependent upon the tab setting. If 
you are in doubt, try seeing how it looks with a tab setting of both 4 and 8 
and see if it still looks reasonable.

It is my intent that a function perform a single task and be kept as short as 
possible to accomplish that task. This often means creating small functions 
to handle sub-tasks. Ctags uses this style throughout and, in my opinion, 
makes the code easier to understand. I do not want ever to see 100+ line 
functions--the only exceptions to this would be large switch statements, but 
then these generally should be used to dispatch control to subroutines. I 
personally have only two violations of this in the ctags code base: one is 
the function cppGet(), a switch statement upon whose perfomance all of the 
speed of ctags depends (allowing parsing well in excess of 1MB/sec) and 
parseParens() of c.c, a monstrosity of a switch() statement of which I am 
particularly ashamed and has made this parser particularly hard to follow and 
fragile to change. Don't make any more of these.

That's all for now. I may formalize these ground rules a little more later.

-- 
Darren Hiebert
http://darrenhiebert.com
http://ctags.sourceforge.net