Re: GNOME programming style standards?

[Miguel de Icaza <miguel nuclecu unam mx>]

> I'm wondering if there are any style standards that GNOME code is
> supposed to follow.  I ask because I just found a rather embarrassing bug
> in a rather embarrassing piece of code:

We tried to use the Linux kernel coding style, but pretty much
everybody chose their own style for their project.

Here are the coding guidelines that I request people for hacking on
Gnumeric:


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 coding style used 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). 
   
   Emacs users can get the default indentation style with this:
  (set-c-style "K&R")
  (setq c-basic-offset 8)

   Do not put a space between a closing parent and an opening bracket.

   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 limited features.

	  Better submit an implementation has been designed to be
	  expanded, enhanced, even if it is not completely finished.

	- 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