Commit 4f8ac399 authored by Arturo Espinosa's avatar Arturo Espinosa

How to hack on Gnumeric, basic guidelines

parent eb3b3858
Hacking on Gnumeric
-------------------
When writing Gnumeric, I have tried to write the code with various
goals in mind:
- Gnumeric code has to be maintainable.
- Gnumeric code needs to be documented.
- Gnumeric code has to be good.
- Gnumeric has to be extensible.
- Gnumeric code has to make sense.
When you submit code to me for inclussion in Gnumeric, or when you
modify the sources directly on the CVS repository, please keep those
things in mind. Specifically, this means:
- Make sure your code does not generate warnings at all.
- Please follow the code style in Gnumeric.
The Gnumeric coding style.
--------------------------
The coding style of Gnumeric is a mix of various styles, make
yourself familiar with the GNU coding standards (shipped with most
GNU/Linux systems as the standards.info file), then read the Linux
kernel coding standards and ignore Linus' jokes. Then look at the
Gtk+ header files to get aquainted on how to write nice header files
that are almost self documenting.
Remember: Use 8 space tabs for indentation: that will keep your
code honest as you will be forced to split your routines in more
modular chunks (as detailed by Linus).
On top of that, you will have to:
- Follow the Gtk+ cleanliness conventions for function
prototypes.
- Follow the Gtk+ namespace convention for function names.
module_submodule_operation
- Make sure your code does not have a single warning (with the
default strong warnings that Gnumeric compiles with) before
your code is submited.
- Every entry point to a public routine should use the
g_return_if_fail and g_return_val_if_fail macros to verify
that the parameters passed are valid.
- Use g_assert internally to establish pre-conditions on the
non-exported routines.
- Under no circunstances use magic variables. Use typedef
enum { ... } type; to create enumerations. Do not use
integers to hold references to enumerations, the compiler
can help catch various errors.
- Use g_warning to mark spots that need to be reviewed or are
not finished to let me fix it eventually.
- Do not submit code that is just a temporary workaround for a
full fledged feature. Ie, dont submit a quick hack at
"search text" which is not designed to be expanded upon. I
do not want to maintain half done features.
- It is more important to be correct than to be fast.
- Do not optimize unnecesarly. Do profile, do look for the
weak spots before applying "optimization by feeling". This
is not a Ouija-based project.
- It is more important to keep the code maintainable and
readable than to be fast. If you have a great idea about
optimizing the code, make sure it is implemented cleanly,
that there is a clean and maintainable way to do it:
- Fast code that is difficult to maintain has no place in
Gnumeric and will be dropped.
- Follow the Gnumeric commenting style.
- Your code should compile without warnings.
- When documenting a function in the comments, please follow
the comment style of the existing code.
- Gnumeric is intended to be ran in various countries with
different currency conventions, number formatting
conventions and different languages. Use the locale
functions to make sure your code will work on countries that
have different conventions than your country.
All of this is to insure the Gnumeric code will be kept within
reasonable margins of maintainability for the future: Remember, in two
years you will probably be very busy to maintain your own
contributions, and it might become a burden to the program maintainers.
Gnumeric is the foundation for a large spreadsheet project and
various other projects in the GNOME desktop (the document model and
CORBA service provision).
Cleaning code in Gnumeric is more important than trying not to
break existing code. By all means, code clean ups are always
welcome.
Extra functions
---------------
When you write new functions, keep the following in mind:
- Be compatible with the Excel functions as much as possible.
- Provide an online help description. If you can provide
examples of use in the documentation, that is even better.
Miguel de Icaza.
October, 1998
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment