Bluefish Coding Style

Bluefish code style

This documents described the conventions to use when coding in the Bluefish project. Please suggest improvements or additions. I'm not a that good C programmer myself ;-)

this is _not_ meant to stop you from coding, but meant to structure the coding a bit. Bluefish isn't very well structured at the moment, and I'm trying to improve this a bit.

happy coding!
Olivier Sessink
http://bluefish.linuxbox.com/

Indenting and formating style

just be lazy and use

indent -kr -ts4 *.c *.h

This is the Kernighan & Ritchie coding style, with tabsize 4

Do not use C++ style comments but use plain C /* and */. gcc does things right, but other C compilers might complain about it.

Naming

use void name_cb() for a callback that can be used global, like the callback to start a dialog (can be something else then a void)

use static void name_lcb() for a local callback, like the OK click in a dialog (can also be something else then a void)

try to have the name explaining what the function does, e.g. doc_do_replace() would do a replace in a specific doc etc.

Declaring procedures

always declare those functions static that need not be visible outside the current file static. Reason: Avoid polluting the global namespace. static functions will be linked only within the same fle. All procedures that are used in other files (public) should be in the .h file declared.

All variables that are used in other files (public) should be in the .h with an extern before it. But try to avoid global variables. Most of the time you can avoid them by creating a typedef struct.

Don't put any extern bla() in the top of a .c file, use #include otherfile.h in there instead. So if you change a function you only have to change that particular .h file. In other words: Declare global functions in the .h file but nowhere else.

New files

If you are writing a new .c file, write a .h file for it too and include the .h file in the .c file. Use include guards in all .h files like

#ifdef __BLUEFISH_H
#define __BLUEFISH_H
... all the declarations here ...
#endif

Reason: allow the compiler to check consistency between the .c and the .h

Which files

This is currently the worst structured:

bluefish.c - start and exit, and some very general functions
document.c - all functions that handle the Tdocument, cut, copy and paste etc.
project.c - all functions that handle the Tproject
callbacks.c - geenral callbacks
cap.c - caps or non caps HTML
coloursel.c - colorselection, this is kind of an own widget
configure.c - configuration dialog
gtk_easy.c - easy GTK shortcuts to reduce repeating code
highlight.c -the synta highlighting code
html.c - dialogs and callbacks
html2.c - dialogs and callbacks
images.c - image and thumbnail dialogs
init.c - parse rcfile and commandline to load options, set defaults for all variables
interface.c - the main GUI itself
network.c - load from web code, a dead link check can be added here as well
ref_dialog.c - the reference dialog
rpopup.c - right click menu and parsing of the HTML into a GList
snr2.c - search and replace, link management (using regex)
stringlist.c - stringlist (GList with strings) handling functionality inc. GUI
toolbars.c - the toolbars including the menu and custom menu (and the buggy custom menu editor)
undo.c - undo/redo
wizards.c -wizards

Patches

Antti-Juhani Kaijanaho wrote:

I keep two code trees of bluefish, one untouched (an official pre unpacked) and one where I do my work. For every unrelated change I make a new tree for my changes.
Before making a patch, run "make patchclean" (or whatever; on projects following the GNU standards that would be "make maintainer-clean") on both trees. "make distclean" should do as well, shouldn't it?
When I want to make a patch, I cd to the parent dir of the two trees. I then run "diff -Naur official-pre-tree my-changed-tree | bzip2 -9c > patchbla.diff.bz2" (where official-pre-tree and my-changed-tree are the two code trees.

Translations

Roland Steinbach (roland@ratisbona.com)wrote:

copy bluefish.pot to gr.po
the msgid-lines have the text to translate, the msgtxt-lines hold the translation
send the .po-file to me or to the list

in future version if you need to update the .po-file you have to:

look for lines containing the word "fuzzy" (except for line 6, here it is right). These are raw guesses of translations, delete the line containig "fuzzy" and correct the translation
look for lines without translations (search for 'msgtxt ""') and translate them.

Some tips

if you want to add a property, add it to Tproperty (in bluefish.h) and set the initialisation line in main_v_props_init() in init.c, that will do. If you want it in the GUI you have to edit configure.c, this should be a line in configure_cb() and a line in apply_config(). Could be more lines for more advanced properties.
gtk_easy.c contains a lot of easy-to-use gtk functions for creating dialogs and setting a lot of variables