[cplp-dev] Request For Comments: Source tree and coding style

[Petras K. <mox...@de...>]

Hello,

We have already had some discussion on the game implementation itself, so
I thought that it would be beneficial for us to work out the source tree
structure and to decide on coding style.

First of all, coding style:

I propose to follow perlstyle manpage as our guideline to coding style.
This means 4 column indent, space before opening curly brackets and
around most operators and so on (consult perlstyle manpage for more).
However, this project is for learning, so I would like to propose the
following additions:

* Subroutine declarations should be well documented, preferably in POD
  format. Subroutine documentation should state purpose of the
  subroutine and how it fits in with the big picture. Sort of like an
  answer to the question "WHY?". This is a learning
  project, too much documentation has not hurt anyone.

* The code should be also commented within the subroutines. This is
  like an answer to the question "HOW?". This is a learning project,
  too much documentation has not anyone.

When you write code for this project, please keep in mind that people
with only some knowledge in the subject will be reading it and trying
to understand. This project is here so that we would learn. Therefore
comment everything: if you are taking a shortcut, add a note about it;
if you are using a complex regexp, comment it; if you are using
complex things with map {}, explain them (things like saying "doing a
Schwartzian transform here" is probably not enough, unless this has
been already explained). Please write readable code, choose readable
variable and function names. The last thing we would want is some Ofbu
code ;)

Now, onto the source code tree. As we have few separate things, we
should try to separate them in the source code. So here is how I see
things:

/doc                   documentation
/src                   source
  |- server            server source code
  |- client            client source code
      |- CGI           CGI client source
      |- console       console client source
      |- ...           any other client source
/themes                themes
  |- perlmonks         default perlmonks theme
      |- maps          perlmonks theme maps
      |- characters    perlmonks theme characters
      |- ...           any other theme resources
  |- ...               any other game theme

Please comment on anything in this email. I am waiting for your input,
ideas and opinions.

-- 
Sėkmės,
 Petras Kudaras                         mailto:mox...@de...