THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.


Samba4 Programming Guide
------------------------

The internals of Samba4 are quite different from previous versions of
Samba, so even if you are an experienced Samba developer please take
the time to read through this document.

This document will explain both the broad structure of Samba4, and
some of the common coding elements such as memory management and
dealing with macros.


Coding Style
------------

In past versions of Samba we have basically let each programmer choose
their own programming style. Unfortunately the result has often been
that code that other members of the team find difficult to read. For
Samba version 4 I would like to standardise on a common coding style
to make the whole tree more readable. For those of you who are
horrified at the idea of having to learn a new style, I can assure you
that it isn't as painful as you might think. I was forced to adopt a
new style when I started working on the Linux kernel, and after some
initial pain found it quite easy.

That said, I don't want to invent a new style, instead I would like to
adopt the style used by the Linux kernel. It is a widely used style
with plenty of support tools available. See Documentation/CodingStyle
in the Linux source tree. This is the style that I have used to write
all of the core infrastructure for Samba4 and I think that we should
continue with that style.

I also think that we should most definately *not* adopt an automatic
reformatting system in cvs (or whatever other source code system we
end up using in the future). Such automatic formatters are, in my
experience, incredibly error prone and don't understand the necessary
exceptions. I don't mind if people use automated tools to reformat
their own code before they commit it, but please do not run such
automated tools on large slabs of existing code without being willing
to spend a *lot* of time hand checking the results.

Finally, I think that for code that is parsing or formatting protocol
packets the code layout should strongly reflect the packet
format. That means ordring the code so that it parses in the same
order as the packet is stored on the wire (where possible) and using
white space to align packet offsets so that a reader can immediately
map any line of the code to the corresponding place in the packet.


Static and Global Data
----------------------

The basic rule is "avoid static and global data like the plague". What
do I mean by static data? The way to tell if you have static data in a
file is to use the "size" utility in Linux. For example if we run:

  size libcli/raw/*.o

in Samba4 then you get the following:

   text    data     bss     dec     hex filename
   2015       0       0    2015     7df libcli/raw/clikrb5.o
    202       0       0     202      ca libcli/raw/clioplock.o
     35       0       0      35      23 libcli/raw/clirewrite.o
   3891       0       0    3891     f33 libcli/raw/clisession.o
    869       0       0     869     365 libcli/raw/clisocket.o
   4962       0       0    4962    1362 libcli/raw/clispnego.o
   1223       0       0    1223     4c7 libcli/raw/clitransport.o
   2294       0       0    2294     8f6 libcli/raw/clitree.o
   1081       0       0    1081     439 libcli/raw/raweas.o
   6765       0       0    6765    1a6d libcli/raw/rawfile.o
   6824       0       0    6824    1aa8 libcli/raw/rawfileinfo.o
   2944       0       0    2944     b80 libcli/raw/rawfsinfo.o
    541       0       0     541     21d libcli/raw/rawioctl.o
   1728       0       0    1728     6c0 libcli/raw/rawnegotiate.o
    723       0       0     723     2d3 libcli/raw/rawnotify.o
   3779       0       0    3779     ec3 libcli/raw/rawreadwrite.o
   6597       0       0    6597    19c5 libcli/raw/rawrequest.o
   5580       0       0    5580    15cc libcli/raw/rawsearch.o
   3034       0       0    3034     bda libcli/raw/rawsetfileinfo.o
   5187       0       0    5187    1443 libcli/raw/rawtrans.o
   2033       0       0    2033     7f1 libcli/raw/smb_signing.o

notice that the "data" and "bss" columns are all zero? That is
good. If there are any non-zero values in data or bss then that
indicates static data and is bad (as a rule of thumb).

Lets compare that result to the equivalent in Samba3:

   text    data     bss     dec     hex filename
   3978       0       0    3978     f8a libsmb/asn1.o
  18963       0     288   19251    4b33 libsmb/cliconnect.o
   2815       0    1024    3839     eff libsmb/clidgram.o
   4038       0       0    4038     fc6 libsmb/clientgen.o
   3337     664     256    4257    10a1 libsmb/clierror.o