[gnome-devel-docs] programming-guidelines: Additional Materials and The Importance of Writing Good Code

[Federico Mena Quintero <federico src gnome org>]

commit 0d2d8715396e6f7758b6b4adf19e6055b53050dc
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Aug 6 11:06:30 2013 +0200

    programming-guidelines: Additional Materials and The Importance of Writing Good Code

 programming-guidelines/C/additional-materials.page |   62 ++++++++++
 programming-guidelines/C/cc-by-sa-3-0.xml          |    9 ++
 programming-guidelines/C/index.page                |   85 ++++++++++++++
 programming-guidelines/C/writing-good-code.page    |  123 ++++++++++++++++++++
 4 files changed, 279 insertions(+), 0 deletions(-)
---
diff --git a/programming-guidelines/C/additional-materials.page 
b/programming-guidelines/C/additional-materials.page
new file mode 100644
index 0000000..e263374
--- /dev/null
+++ b/programming-guidelines/C/additional-materials.page
@@ -0,0 +1,62 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide" style="task"
+      id="additional-materials">
+
+  <info>
+    <link type="guide" xref="index#references"/>
+    
+    <credit type="author copyright">
+      <name>Federico Mena-Quintero</name>
+      <email>federico gnome org</email>
+      <years>2013</years>
+    </credit>
+
+    <desc>Other style guides and books about organizing free software
+    projects</desc>
+  </info>
+
+  <title>Additional Materials</title>
+
+  <p>
+    Here we give you links to other materials that you may want to
+    read.  These will teach you a lot about how to work on large
+    distributed teams of free software developers, and about good
+    programming style in general.
+  </p>
+
+  <list>
+    <item>
+      <p>
+       <link href="http://producingoss.com/";>Produducing Open Source
+       Software</link>, by Karl Fogel.  This is a truly excellent
+       book of good practices that free software projects should
+       follow.  This is about <em>social aspects</em> of the project:
+       how to treat contributors, how to organize and moderate
+       communication, how to deal with non-profit foundations.  If
+       you ask yourself at any time, "how should I deal with
+       $human_situation in the project?", this book may provide the
+       answer.
+      </p>
+    </item>
+
+    <item>
+      <p>
+       <link href="http://www.gnu.org/prep/standards/";>GNU Coding
+       Standards</link>.  This is an old document, but it still has
+       lots of excellent advice.  It talks about C coding style,
+       issues when dealing with plug-in systems, common option names
+       for command-line programs, conventions for Makefiles, and some
+       very GNU-ish details like using Texinfo for documentation.
+      </p>
+    </item>
+
+    <item>
+      <p>
+       <link href="https://www.kernel.org/doc/Documentation/CodingStyle";>Linux
+       Kernel Coding Style</link>.  Explains the rationale for "big
+       indentation", brace placement, concise but unambiguous naming,
+       and centralized exit of functions.
+      </p>
+    </item>
+  </list>
+</page>
diff --git a/programming-guidelines/C/cc-by-sa-3-0.xml b/programming-guidelines/C/cc-by-sa-3-0.xml
new file mode 100644
index 0000000..6f643be
--- /dev/null
+++ b/programming-guidelines/C/cc-by-sa-3-0.xml
@@ -0,0 +1,9 @@
+<license xmlns="http://projectmallard.org/1.0/";
+         href="http://creativecommons.org/licenses/by-sa/3.0/us/";>
+<p>This work is licensed under a
+<link href="http://creativecommons.org/licenses/by-sa/3.0/us/";>Creative Commons
+Attribution-Share Alike 3.0 United States License</link>.</p>
+<p>As a special exception, the copyright holders give you permission to copy,
+modify, and distribute the example code contained in this document under the
+terms of your choosing, without restriction.</p>
+</license>
diff --git a/programming-guidelines/C/index.page b/programming-guidelines/C/index.page
new file mode 100644
index 0000000..8c7ed78
--- /dev/null
+++ b/programming-guidelines/C/index.page
@@ -0,0 +1,85 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide" style="task"
+      id="index">
+
+  <info>
+    <credit type="author copyright">
+      <name>Federico Mena-Quintero</name>
+      <email>federico gnome org</email>
+      <years>2013</years>
+    </credit>
+    <credit type="author copyright">
+      <name>Miguel de Icaza</name>
+      <email>miguel gnome org</email>
+    </credit>
+    <credit type="author copyright">
+      <name>Morten Welinder</name>
+      <email>mortenw gnome org</email>
+    </credit>
+    <credit type="publisher">
+      <name>GNOME Foundation</name>
+      <page xmlns="http://xmlns.com/foaf/0.1/";>http://foundation.gnome.org/</page>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+    <desc>Gnome Programming Guidelines</desc>
+
+    <title type="link" role="trail">Programming Guidelines</title>
+  </info>
+
+  <title>Gnome Programming Guidelines</title>
+
+  <p>
+    This article contains several guidelines and suggestions for Gnome
+    programmers, as well as certain policies that should be followed
+    when writing Gnome programs.  This is intended for programmers to
+    know about Gnome's development process and its philosophy.
+    Gnome is a team effort, so it will be useful for programmers to
+    know "the way things are done".  Think of this document not as a
+    book of laws, but rather as a manual of etiquette for writing
+    legible code that an be maintained by large, diverse teams over a
+    long period of time.
+  </p>
+
+  <p>
+    This guide has a two-fold purpose:
+  </p>
+
+  <list>
+    <item>
+      <p>
+       To give you good suggestions on how to write code for Gnome.
+       This will help you write code that is consistent with Gnome's
+       practices, and that is well-accepted by the members of the
+       Gnome community.  This will also lead to code that is a
+       pleasure to work on.
+      </p>
+    </item>
+
+    <item>
+      <p>
+       To transmit the knowledge we have gotten over the years on how
+       to keep the Gnome project sustainable, even when people's
+       contributions increase or decrease.
+      </p>
+    </item>
+  </list>
+
+  <section id="coding-style">
+    <info>
+      <title type="link" role="trail">Coding Style</title>
+    </info>
+    <title>Coding Style</title>
+    <links type="topic" groups="coding-style" style="grid center"/>
+  </section>
+
+  <section id="references">
+    <info>
+      <title type="link" role="trail">References</title>
+    </info>
+    <title>References</title>
+    <links type="topic" groups="references" style="grid center"/>
+  </section>
+
+</page>
diff --git a/programming-guidelines/C/writing-good-code.page b/programming-guidelines/C/writing-good-code.page
new file mode 100644
index 0000000..2bfbb5e
--- /dev/null
+++ b/programming-guidelines/C/writing-good-code.page
@@ -0,0 +1,123 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide" style="task"
+      id="writing-good-code">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+    
+    <credit type="author copyright">
+      <name>Federico Mena-Quintero</name>
+      <email>federico gnome org</email>
+      <years>2013</years>
+    </credit>
+    <credit type="author copyright">
+      <name>Miguel de Icaza</name>
+      <email>miguel gnome org</email>
+    </credit>
+    <credit type="author copyright">
+      <name>Morten Welinder</name>
+      <email>mortenw gnome org</email>
+    </credit>
+
+    <desc>Good, readable code keeps the project maintainable</desc>
+  </info>
+
+  <title>The Importance of Writing Good Code</title>
+
+  <p>
+    Gnome is a very ambitious free software project, and it is
+    composed of many software packages that are more or less
+    independent of each other.  A lot of the work in Gnome is done by
+    volunteers:  although there are many people working on Gnome
+    full-time or part-time for here, volunteers still make up a large
+    percentage of our contributors.  Programmers may come and go at
+    any time and they will be able to dedicate different amounts of
+    time to the Gnome project.  People's "real world" responsibilities
+    may change, and this will be reflected in the amount of time and
+    they can devote to Gnome.
+  </p>
+
+  <p>
+    Software development takes long amounts of time and painstaking
+    effort.  This is why most part-time volunteers cannot start big
+    projects by themselves; it is much easier and more rewarding to
+    contribute to existing projects, as this yields results that are
+    immediately visible and usable.
+  </p>
+
+  <p>
+    Thus, we conclude that it is very important for existing projects
+    to make it as easy as possible for people to contribute to them.
+    One way of doing this is by making sure that programs are easy to
+    read, understand, modify, and maintain.
+  </p>
+
+  <p>
+    Messy code is hard to read, and people may lose interest if they
+    cannot decipher what the code tries to do.  Also, it is important
+    that programmers be able to understand the code quickly so that
+    they cna start contributing with bug fixes and enhancements in a
+    short amount of time.  Source code is a form of
+    <em>communication</em>, and it is more for people than for
+    computers.  Just as someone would not like to read a nvoel with
+    spelling errors, bad grammar, and sloppy punctuation, programmers
+    should strive to write good code that is easy to understand and
+    modify by others.
+  </p>
+
+  <p>
+    The following are some important qualities of good code:
+  </p>
+
+  <terms>
+    <item>
+      <title>Cleanliness</title>
+      <p>
+       Clean code is easy to read with minimum effort.  This lets
+       people start to understand it easily.  This includes the
+       coding style itself (brace placement, indentation, variable
+       names), and the actual control flow of the code.
+      </p>
+    </item>
+
+    <item>
+      <title>Consistency</title>
+      <p>
+       Consistent code makes it easy for people to understand how a
+       program works.  When reading cnsistent code, one
+       subconsciously forms a number of assumptions and expectations
+       about how the code works, so it is easier and safer to make
+       modifications to it.  Code that <em>looks</em> the same in two
+       places should <em>work</em> the same, too.
+      </p>
+    </item>
+
+    <item>
+      <title>Extensibility</title>
+      <p>
+       General-purpose code is easier to reuse and modify than very
+       specific code with lots of hardcoded assumptions.  When
+       someone wants to add a new feature to a program, it will
+       obviously be easier to do so if the code was designed to be
+       extensible from the beginning.  Code that was not written this
+       way may lead people into having to implement ugly hacks to add
+       features.
+      </p>
+    </item>
+
+    <item>
+      <title>Correctness</title>
+      <p>
+       Finally, code that is designed to be correct lets people spend
+       less time worrying about bugs, and more time enhancing the
+       features of a program.  Users also apprciate correct code,
+       since nobody likes software that crashes.  Code that is
+       written for correctness and safety (i.e. code that explicitly
+       tries to ensure that the program remains in a consistent
+       state) prevents many kinds of silly bugs.
+      </p>
+    </item>
+  </terms>
+
+
+</page>