mirror of
https://gitlab.gnome.org/GNOME/nautilus
synced 2024-09-19 15:51:40 +00:00
292a29b61f
* check-config-h.pl: Wrote a script to check for files that forget to include <config.h> and optionally edit to add it. * src/nautilus-zoom-control.c (set_zoom_level): Fixed the bug number in a FIXME. * docs/style-guide.html: Added one more tip. * check-FIXME.pl: Use my newfound Perl knowledge to spruce it up. * components/help/converters/gnome-db2html2/gdb3html.c: * components/help/converters/gnome-db2html2/sect-elements.c: * components/help/converters/gnome-db2html2/sect-preparse.c: * components/help/converters/gnome-db2html2/toc-elements.c: * components/help/converters/gnome-info2html2/html.c: * components/help/converters/gnome-info2html2/main.c: * components/help/converters/gnome-info2html2/parse.c: * components/help/converters/gnome-info2html2/utils.c: * components/help/converters/gnome-man2html2/gnome-man2html.c: * components/help/hyperbola-filefmt.c: * components/help/hyperbola-nav-index.c: * components/help/hyperbola-nav-search.c: * components/help/hyperbola-nav-tree.c: * components/html/glibwww-callbacks.c: * components/html/glibwww-init.c: * components/html/glibwww-trans.c: * components/html/gnome-dialogs.c: * components/html/ntl-web-browser.c: * components/services/install/eazel-install-metadata.c: * components/services/install/eazel-install-protocols.c: * components/services/install/eazel-install-rpm-glue.c: * components/services/install/eazel-install-tests.c: * components/services/install/eazel-install-utils.c: * components/services/install/eazel-install-xml-package-list.c: * components/services/install/eazel-install.c: * components/services/install/helixcode-install-utils.c: * components/services/startup/eazel-register.c: * components/websearch/ntl-web-search.c: * helper-utilities/authenticate/nautilus-authenticate-fork.c: * helper-utilities/authenticate/nautilus-authenticate-pam.c: * helper-utilities/authenticate/nautilus-authenticate.c: * libnautilus-extensions/nautilus-bonobo-extensions.c: * libnautilus-extensions/nautilus-file-utilities.c: * libnautilus-extensions/nautilus-glib-extensions.c: * libnautilus-extensions/nautilus-link.c: * libnautilus-extensions/nautilus-mime-type.c: * libnautilus-extensions/nautilus-undo-transaction.c: * librsvg/art_rgba.c: * librsvg/art_rgba_svp.c: * librsvg/rsvg-bpath-util.c: * librsvg/rsvg-path.c: * librsvg/rsvg.c: * librsvg/test-rsvg.c: * nautilus-widgets/nautilus-caption-table.c: * nautilus-widgets/nautilus-password-dialog.c: * nautilus-widgets/nautilus-preferences-box.c: * nautilus-widgets/nautilus-preferences-dialog.c: * nautilus-widgets/nautilus-preferences-group.c: * nautilus-widgets/nautilus-preferences-item.c: * nautilus-widgets/nautilus-preferences-pane.c: * nautilus-widgets/nautilus-radio-button-group.c: * nautilus-widgets/test-nautilus-widgets.c: * nautilus-widgets/test-preferences.c: * src/file-manager/desktop-item.c: * src/file-manager/desktop-layout.c: * src/file-manager/desktop-menu.c: * src/nautilus-bookmarks-window.c: * src/nautilus-gconf.c: * src/nautilus-window-menus.c: * src/nautilus-window-toolbars.c: * src/nautilus-zoom-control.c * src/nautilus-zoomable-frame-svr.c: * src/ntl-app.c: * src/ntl-content-view.c: * src/ntl-main.c: * src/ntl-meta-view.c: * src/ntl-miniicon.c: * src/ntl-uri-map.c: * src/ntl-view-frame-svr.c: * src/ntl-view.c: * src/ntl-window-state.c: Added includes of <config.h>.
140 lines
5.2 KiB
HTML
140 lines
5.2 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Nautilus Coding Style Guide</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<p>To make code written for Nautilus look and act in a predictable way,
|
|
we follow a set of guidelines that specify some details of how we write code.
|
|
To start, we follow all the guidelines outlined in the
|
|
<a href="http://developer.gnome.org/doc/guides/programming-guidelines/">GNOME Programming Guidelines</a>.</p>
|
|
|
|
<p>This document covers both things that are not mentioned in the GNOME
|
|
Programming Guidelines and things that are mentioned there but need
|
|
to be re-emphasized because people don't follow them often enough.</p>
|
|
|
|
<p>I'm just getting started on this document. Feedback is welcome.
|
|
Eventually I'd like better organization and tons of examples.</p>
|
|
|
|
<blockquote>
|
|
<p>- <a href="mailto:darin@eazel.com">Darin</a></p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
|
|
<p><b>We use the most-recommended coding style from the GNOME Programming
|
|
Guidelines.</b> This means that we use the Linux kernel brace style with
|
|
8-character tabs (not the GNU brace style), we put spaces before
|
|
the parentheses that introduce function argument lists, we put the
|
|
braces that open the block for an if statement on the same line as the
|
|
if statement (part of Linux kernel brace style).</p>
|
|
|
|
<p><b>We prefer to use words rather than acronyms or abbreviations.</b> This means that
|
|
we name classes with a prefix like Nautilus, not Ntl, for example. And we use variables
|
|
named result rather than retval or rv.</p>
|
|
|
|
<p><b>We strive to have a minimum number of local variables.</b> This makes it
|
|
easier to move pieces of code around. For more on this, read
|
|
<a href="recommended-books.html#Refactoring"><i>Refactoring</i></a>.</p>
|
|
|
|
<p><b>We use type casts as little as possible.</b> There are many places in GTK programming
|
|
where you have to cast to make the program work, but we do whatever we can
|
|
to avoid this. Also, we prefer to cast data pointers, rather than casting
|
|
function pointers, since there's so much more to get wrong with function
|
|
pointer casts.</p>
|
|
|
|
<p><b>We use typedefs from <glib.h> for things like guint and gpointer,
|
|
but not gint, gchar, or gdouble.</b> Using these gives a false sense
|
|
of portability. In all three cases, using system calls like printf requires
|
|
knowing that these are the "real" int, char, and double, so there's no reason
|
|
to use a typedef that's non-standard.</p>
|
|
|
|
<p><b>We avoid in-band signaling.</b> This means that we avoid using special
|
|
values to indicate errors, for example. This can lead to subtle bugs when a valid
|
|
result is misinterpreted as an error, and can make it hard to tell if the code
|
|
handles errors or not.</p>
|
|
|
|
<p><b>We code for clarity first.</b> Other concerns like efficiency are secondary.
|
|
Sometimes they become more important than clarity, but only once they are proven
|
|
to be a problem.</p>
|
|
|
|
<p><b>We use for loops when they make the code easier to read.</b> The alternative
|
|
is usually to use a while loop. It's true that
|
|
"easy to read" is a subjective thing.</p>
|
|
|
|
<p><b>We declare local variables at the top of the function.</b> C allows you
|
|
to declare variables at the top of any scope, like the scope in a control
|
|
flow construct like an if statement. But putting the declarations there makes
|
|
it harder to add and delete if statements, since the declarations have to move.
|
|
So we just put them all at the top of the function, usually in the order that
|
|
they are used in the function.</p>
|
|
|
|
<p><b>We do not initialize local variables in their declarations.</b> C allows you
|
|
to initialize a local variable when declaring it. But no other code can run before
|
|
this, because the other statements in a function must be after all the declarations.
|
|
If there are lines of code initializing the variables in the declarations, it can
|
|
be harder to change the function around, since code must move down from the declaration
|
|
if other code needs to run after it. To avoid this, we just don't use the ability
|
|
to initialize the variable when it's declared.</p>
|
|
|
|
<p><b>We always use braces, even for one-statement "blocks".</b> Our consensus is
|
|
to do things like this:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
if (list != NULL) {
|
|
g_warning ("the list isn't empty");
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Instead of this:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
if (list != NULL)
|
|
g_warning ("the list isn't empty");
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>This applies to all control structures: if, while, for, do.</p>
|
|
|
|
<p><b>We make each header "stand alone".</b> Our concept with C header files is
|
|
that each one must be written so it can be included without including another file
|
|
first. To test that the header files we develop have this property, we always
|
|
include the corresponding header file first in each C source file. The only exception
|
|
is the include of <config.h>, which goes first. Here's an example:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*-
|
|
*
|
|
* nautilus-icon-factory.c: Class for obtaining icons for files and other objects.
|
|
*
|
|
* Copyright (C) 1999, 2000 Red Hat Inc.
|
|
* Copyright (C) 1999, 2000 Eazel, Inc.
|
|
*
|
|
* <i>License agreement goes here.</i>
|
|
*
|
|
* Author: John Sullivan <sullivan@eazel.com>
|
|
*/
|
|
|
|
#include <config.h>
|
|
#include "nautilus-icon-factory.h"
|
|
|
|
#include <string.h>
|
|
#include <stdio.h>
|
|
<i>Include statements for other header files go here.</i>
|
|
|
|
<i>Other declarations and code go here.</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
|
|
</body>
|
|
|
|
</html>
|