Revision: 4571 http://geany.svn.sourceforge.net/geany/?rev=4571&view=rev Author: ntrel Date: 2010-01-28 13:10:44 +0000 (Thu, 28 Jan 2010)
Log Message: ----------- Backport from trunk: Add 'Compiler options & warnings' section. Update Style section to be clearer about code alignment and show some example code. Other minor edits.
Modified Paths: -------------- branches/geany-0.18.1/ChangeLog branches/geany-0.18.1/HACKING
Modified: branches/geany-0.18.1/ChangeLog =================================================================== --- branches/geany-0.18.1/ChangeLog 2010-01-28 13:06:19 UTC (rev 4570) +++ branches/geany-0.18.1/ChangeLog 2010-01-28 13:10:44 UTC (rev 4571) @@ -3,6 +3,11 @@ * src/keybindings.c: Fix 'Reflow block' command when at the last paragraph and there's no last newline (patch by Eugene Arshinov, thanks). + * HACKING: + Add 'Compiler options & warnings' section. + Update Style section to be clearer about code alignment and show + some example code. + Other minor edits.
2009-09-01 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
Modified: branches/geany-0.18.1/HACKING =================================================================== --- branches/geany-0.18.1/HACKING 2010-01-28 13:06:19 UTC (rev 4570) +++ branches/geany-0.18.1/HACKING 2010-01-28 13:10:44 UTC (rev 4571) @@ -48,12 +48,15 @@
$ diff -u originalpath modifiedpath > new-feature.patch
-Please make sure patches follow the style of existing code - In -particular, use tabs for indentation. See `Style`_ and `Coding`_. +.. note:: + Please make sure patches follow the style of existing code - In + particular, use tabs for indentation. See `Coding`_.
-For Windows: -Subversion (SVN): http://subversion.tigris.org/ -diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/. +Windows tools +------------- +* Subversion (SVN): http://subversion.tigris.org/ +* diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/ + See also the 'Building on Windows' document on the website.
File organization @@ -91,7 +94,7 @@ If you're in any doubt when making changes to plugin API code, just ask us.
Plugin API/ABI design ---------------------- +^^^^^^^^^^^^^^^^^^^^^ You should not make plugins rely on the size of a struct. This means:
* Don't let plugins allocate any structs (stack or heap). @@ -130,36 +133,89 @@ * Don't write long functions with a lot of variables and/or scopes - break them down into smaller static functions where possible. This makes code much easier to read and maintain. -* Use GLib types and functions - e.g. g_free instead of free. +* Use GLib types and functions - gint not int, g_free() not free(). * Your code should build against GLib 2.8 and GTK 2.8. At least for the moment, we want to keep the minimum requirement for GTK at 2.8 (of course, you can use the GTK_CHECK_VERSION macro to protect code using later versions). -* We currently try to support the old GCC 2.9.x compiler, - so we always declare variables before statements. You can use - -Wdeclaration-after-statement in your ./configure CFLAGS to warn about - this. -* You should also try to write ISO C90 code for portability, so always +* Variables should be declared before statements. You can use + gcc's -Wdeclaration-after-statement to warn about this. +* Don't let variable names shadow outer variables - use gcc's -Wshadow + option. + +Compiler options & warnings +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh`` +to set warning options (as well as anything else e.g. -g -O2). + +* Enable warnings - for gcc use '-Wall -W' (and optionally + -Wno-unused-parameter to avoid unused parameter warnings in Glade + callbacks). +* You should try to write ISO C90 code for portability, so always use C ``/* */`` comments and function_name(void) instead of - function_name(). This is for compatibility with various Unix-like - compilers. You can use -ansi in your CFLAGS to help check this. + function_name(). This is for compatibility with various Unix-like + compilers. You should use -ansi to help check this.
Style ------ +^^^^^ * We use a tab width of 4 and indent completely with tabs not spaces. * Use the multiline comment ``/* */`` to comment small blocks of code, functions descriptions or longer explanations of code, etc. C++ single line comments will cause portability issues. The more comments are in - your code the better. + your code the better. (See also ``scripts/fix-cxx-comments.pl`` in SVN). * Lines should not be longer than about 100 characters and after 100 - characters the lines should be wrapped and more indented than the first - line to highlight that the line is continued. + characters the lines should be wrapped and indented once more to + show that the line is continued. * We don't put spaces between function names and the opening brace for argument lists. -* Try to fit in with the existing code brace indenting style, comments, - operator spacing etc. It's not required for patches but it will save - us having to manually reformat them. +* Variable declarations come first after an opening brace, then one + newline to separate declarations and code. +* 2-operand operators should have a space each side. +* Function bodies should have 2 blank newlines after them. +* Align braces together on separate lines. +* Don't put assignments in 'if/while/etc' expressions. +* if statements without brace bodies should have the code on a separate + line, then a blank line afterwards. +* Use braces after if/while statements if the body uses another + if/while statement. +* Try to fit in with the existing code style.
+.. note:: + A few of the above can be done with the SVN + ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better + to write it correctly in the first place. + +.. below tabs should be used, but spaces are required for reST. + +Example:: + + gint some_func(void); + + + gint function_long_name(gchar arg1, <too many args to fit on this line>, + gchar argN) + { + gint foo; + + if (foo) + { + gint dir = -1; /* -1 to search backwards */ + + bar = foo; + if (bar != 7) + some_code(arg1, <too many args to fit on this line>, + argN - 1, argN); + + some_func(); + } + } + + + gint another_function(void) + { + ... + + Libraries --------- We prefer to use an unmodified version of Scintilla - any changes should
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.