* Please COMMENT everything which is not trivial. Add comments for each
source file, function, variables and whatever is not easily self explaining.
I propose something like my comment templates in
`bloodspilot2-clients/src/comment_templates.txt'.
Comments are not a waste of time. To the contrary, they safe time. They
are not only a help to other developers, but also help yourself to clarify
what you intent to do. And the older any code gets, the more valuable
comments become.
* DOCUMENTATION should be put under source code management control (git).
Perhaps use HTML with nicely structured and numbered chapters.
From this source the doc can be put on a website for online browsing and
can also be shipped along with the client.
I don't think we need to maintain comprehensive Unix-style manpages (with
redundant information), but perhaps have very brief manpages for the
respective programs (client, server, replay, etc.), which simply refer to
the HTML documentation.
* A related old todo entry of mine: ADD DEVELOPER GUIDELINES/DOCUMENTATION:
Explain how certain things in XPilot/bloodspilot work. The source code to
both server and client is quite large and it has grown over 2 decades, with
contributions from many people. The names of all the source files can give
a rough idea about what they contain, but often one does not know where
something is done. Also functions, macros, variables, type definitions,
constants etc are sometimes not in the best suitable file. It would be
nice if each file had a comment close to the top, with a brief description
of the purpose of the file and what it contains.
Add comments!!! It is a bad help to the community and probably to yourself,
to write (complicated) code without (meaningful) descriptions. Another
developer can understand much quicker what is done and how something works
when there are descriptive comments. And not least, while you comment your
code, you will understand it better yourself.
I find it helpful to write the function description first along with the
function name, its arguments, argument and result description. Only when
these things are clear, it is time to start writing the actual function code.
Also note in the function description which side effects occur, like use or
even modification of global or "file-global" variables.
State any deficiencies, hacks and what you think should be improved.
When several functions work together to do some task, do also explain that.
Have a look at the related GNU coding standards
section. From a shell run:
`info standards "Writing C" Comments'.
It's a good manual and can be read within perhaps 10 minutes or less.
Try to find meaningful names for files, functions, macros, variables etc.
The code will be easier to understand. Add a comment at each name
declaration (function, macro, variable, type, constant etc.), describing
its meaning and intended use.
Provide templates for file, function and macro descriptions.
Add templates/style guides for client/server options.
Give naming recommendations, state what the help text should contain (and
what not), how much to put into the help text and recommend a single text
layout, i.e. line length, indentation etc.
I don't think we need to bother writing tidy HTML formatted developer
documentation. Just plain text files should do. They should also be kept
under source code control in some place like `documentation/development'
and appropriate sub directories like `server', `client' etc.