Re: Developer Guide

[Samy Al Bahra <samy at kerneled dot com>]

Quoting Muhammad Alkarouri <malkarouri at yahoo dot co dot uk>:

> > Heh.. well, I could instead be asking everyone to create full fledged
> > documents in SGML detailing their code ;) Doxygen is rather simple and
> > aside from the configuration file (which is not an issue -- many IDE's
> > and helper programs exist to generate it for you), the commenting style
> > is simple and not a serious issue.

SGML is very popular. I prefer it personally. The fact is ElZubeir, you
should NOT require that all our code be documented with doxygen, UNLESS,
you do force a uniform coding/commenting style so one DOxygen setup
can be used to generate actual documentation. I am not familiar with
DOxygen and so are a lot of others, you shouldn't force them into learning
it. Code should ATLEAST be well commented and the program itself should
ATLEAST contain documentation on how to use the program, how to install,
etc... (the usual stuff).

> Actually, I meant DocUtils, as in http://docutils.sourceforge.net , but
> leave it for now. We don't have many Python projects (anything besides
> Duali?) and when there are many, we can standardize.

DocBook is pretty popular too.

> Sorry, Samy. But I think it will be a huge burden to enforce it. I mean,
> porting Katoob to FreeBSD should be made as easy as possible, but assuming
> that the coder is not that skillful in FreeBSD I don't think he should stop
> releasing the software.

No, it is not a huge burden. Do all you really think some sort of magical
power maintains all these operating systems? We're all running on the same
standards, the same API, etc... GOOD code and a GOOD build framework should
allow decent portability unless we're looking at things that truly are
system specific (a program that directly, *directly* interacts with Linux
unicode terminal settings for example). A program like Katoob or like
Duali should be portable enough to run on different platforms. Something
like ITL should not be Linux-specific. A program like Akka should take
into consideration other platforms and not ignore it.

The programmer does not have to be skillfull in FreeBSD, the programmer
needs to know the he should be operating under the bounds of UNIX/POSIX
API and other standards. He should blindly be using distribution specific
include and library paths but rather have some sort of detection, aka
use autotools (-l/opt/somelinuxpathblahblah).

OPENSOURCE IS NOT ALL ABOUT LINUX. Remember that.

-- 
+-----------------------------------+
| Samy Al Bahra | samy at kerneled dot com |
|-----------------------------------|
|     B3A7 F5BE B2AE 67B1 AC4B      |
|     0983 956D 1F4A AA54 47CB      |
|-----------------------------------|
|     http://www.kerneled.com       |
+-----------------------------------+