GNOME.org
 

[gnome-devel-docs/wip/gjs-style-guide] WIP Add GJS JavaScript style guide

commit 83fad3ca0f9acc7f806972e68415d1b98133991f
Author: David King <amigadave amigadave com>
Date:   Tue Jun 18 23:37:01 2013 +0100

    WIP Add GJS JavaScript style guide

 Makefile.am                             |    1 +
 configure.ac                            |    1 +
 gjs-style-guide/C/declarations.page     |   33 ++++++++++++++++
 gjs-style-guide/C/general.page          |   31 +++++++++++++++
 gjs-style-guide/C/gobject-concepts.page |   63 +++++++++++++++++++++++++++++++
 gjs-style-guide/C/index.page            |   33 ++++++++++++++++
 gjs-style-guide/C/legal.xml             |   11 +++++
 gjs-style-guide/C/variables.page        |   37 ++++++++++++++++++
 gjs-style-guide/C/whitespace.page       |   31 +++++++++++++++
 gjs-style-guide/Makefile.am             |   16 ++++++++
 10 files changed, 257 insertions(+), 0 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index afa38fe..317b1be 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,7 @@
 SUBDIRS =                              \
        accessibility-devel-guide       \
        platform-demos                  \
+       gjs-style-guide                 \
        hig                             \
        integration-guide               \
        optimization-guide              \
diff --git a/configure.ac b/configure.ac
index 8f4c32a..cca798f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -10,6 +10,7 @@ AC_OUTPUT([
 Makefile
 accessibility-devel-guide/Makefile
 platform-demos/Makefile
+gjs-style-guide/Makefile
 hig/Makefile
 integration-guide/Makefile
 optimization-guide/Makefile
diff --git a/gjs-style-guide/C/declarations.page b/gjs-style-guide/C/declarations.page
new file mode 100644
index 0000000..eb9a90c
--- /dev/null
+++ b/gjs-style-guide/C/declarations.page
@@ -0,0 +1,33 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="declarations">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>Declaring and defining variables.</desc>
+  </info>
+
+  <title>Declarations</title>
+
+  <p>JavaScript has scoping rules that differ from most other programming
+  languages, and require some care to use correctly. Some simple rules help to
+  make this more consistent.</p>
+
+<list>
+  <item><p>Always use either <code>const</code>, <code>var</code> or
+  <code>let</code> when defining a variable</p></item>
+  <item><p>The default is <em>function scope</em>, so use <code>let</code> for
+  variables in <code>while</code> and <code>for</code> loops</p></item>
+</list>
+
+</page>
diff --git a/gjs-style-guide/C/general.page b/gjs-style-guide/C/general.page
new file mode 100644
index 0000000..db0eef3
--- /dev/null
+++ b/gjs-style-guide/C/general.page
@@ -0,0 +1,31 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="general">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>General style guidelines.</desc>
+  </info>
+
+  <title>General style</title>
+
+  <p>Some basic and important style guidelines.</p>
+
+<list>
+  <item><p>Always end statements with a semicolon, even though it is not
+  required</p></item>
+  <item><p>Use <code>CamelCase</code> when creating aliases for
+  <code>imports</code></p></item>
+</list>
+
+</page>
diff --git a/gjs-style-guide/C/gobject-concepts.page b/gjs-style-guide/C/gobject-concepts.page
new file mode 100644
index 0000000..869ed9b
--- /dev/null
+++ b/gjs-style-guide/C/gobject-concepts.page
@@ -0,0 +1,63 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="gobject-concepts">
+
+  <info>
+    <link type="guide" xref="index#gobject"/>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>Mapping GObject concepts to JavaScript.</desc>
+  </info>
+
+  <title>GObject concepts</title>
+
+  <p>Accessing features of GObject libraries from JavaScript.</p>
+
+<section>
+  <title>Objects</title>
+
+  <p><em>Constructors</em> appear just like JavaScript constructors, and can
+  take a map of properties:</p>
+
+  <code>let actor = new Clutter.Group({ reactive: true, width: 100, height: 100 });</code>
+
+  <p>Connect <em>signals</em> using the <code>connect</code> method, which is
+  on every GObject:</p>
+
+  <code>actor.connect('button-press-event', function (actor, event) {
+  ...
+});</code>
+
+  <p><em>Properties</em> are accessed using JavaScript-style property
+  access:</p>
+
+  <code>box.y_align = Big.BoxAlignment.CENTER;</code>
+
+  <p><em>Enumerations</em> and <em>flags</em> appear as entries in a namespace,
+  with associated member properties:</p>
+
+  <code>Gtk.WindowType.TOPLEVEL;</code>
+
+  <p><em>Structures</em> have a JavaScript property for each member, which
+  should generally be treated as read-only.</p>
+
+  <p>For a C function with <em>multiple out parameters</em>, the return values
+  are collected into an array:</p>
+
+  <code>let [x, y] = actor.get_size();</code>
+
+  <p>If the function has a return value in addition to the out parameters, the
+  return value will be the first element of the returned array:</p>
+
+  <code>let [success, appExec, count, time] = myGtkRecentInfo.get_application_info(appName);</code>
+</section>
+
+</page>
diff --git a/gjs-style-guide/C/index.page b/gjs-style-guide/C/index.page
new file mode 100644
index 0000000..7b3f0cd
--- /dev/null
+++ b/gjs-style-guide/C/index.page
@@ -0,0 +1,33 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="guide"
+      id="index">
+
+  <info>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>Guidelines for writers for the GNOME platform.</desc>
+  </info>
+
+  <title>Good GNOME JavaScript Style</title>
+
+  <p>JavaScript is a flexible programming language with a lightly-restricted
+  form. GNOME JavaScript code uses a style which is designed to promote
+  readability, consistency and maintanability.</p>
+
+<section id="coding-style">
+  <title>Coding Style</title>
+</section>
+
+<section id="gobject">
+  <title>Using GObjects from JavaScript</title>
+</section>
+
+</page>
diff --git a/gjs-style-guide/C/legal.xml b/gjs-style-guide/C/legal.xml
new file mode 100644
index 0000000..3712606
--- /dev/null
+++ b/gjs-style-guide/C/legal.xml
@@ -0,0 +1,11 @@
+<license xmlns="http://projectmallard.org/1.0/";
+         href="http://creativecommons.org/licenses/by-sa/3.0/";>
+
+  <p>This work is licensed under a
+  <link href="http://creativecommons.org/licenses/by-sa/3.0/";>Creative Commons
+  Attribution-ShareAlike 3.0 Unported 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 documentation under
+  the terms of your choosing, without restriction.</p>
+</license>
diff --git a/gjs-style-guide/C/variables.page b/gjs-style-guide/C/variables.page
new file mode 100644
index 0000000..36df9c2
--- /dev/null
+++ b/gjs-style-guide/C/variables.page
@@ -0,0 +1,37 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="variables">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>Naming variables.</desc>
+  </info>
+
+  <title>Variables</title>
+
+  <p>Consistent naming rules make it easier to see the ownership and scope of
+  variables while looking at source code.</p>
+
+<list>
+  <item><p>Use <code>CamelCase</code> for type names and
+  <code>lowerCamelCase</code> for variable and method names</p></item>
+  <item><p>Use a leading underscore for private variables</p></item>
+  <item><p>Avoid using global variables</p></item>
+  <item><p>When renaming a variable to avoid a namespace collision, add a
+  trailing underscore to the name</p></item>
+  <item><p>When constructing a GObject, use <code>lowerCamelCase</code> style
+  for property names, instead of using dashes or underscores as with
+  C</p></item>
+</list>
+
+</page>
diff --git a/gjs-style-guide/C/whitespace.page b/gjs-style-guide/C/whitespace.page
new file mode 100644
index 0000000..66f359e
--- /dev/null
+++ b/gjs-style-guide/C/whitespace.page
@@ -0,0 +1,31 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="whitespace">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+    <revision pkgversion="3.9.4" version="0.1" date="2013-06-18" status="stub"/>
+    
+    <credit type="author">
+      <name>David King</name>
+      <email its:translate="no">davidk gnome org</email>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"; />
+
+    <desc>Indentation and space around code.</desc>
+  </info>
+
+  <title>Whitespace</title>
+
+  <p>Using whitespace consistently makes it easy to see logical breaks in
+  source code.</p>
+
+<list>
+  <item><p>Only use spaces for whitespace</p></item>
+  <item><p>Indent by 4 spaces</p></item>
+  <item><p>Only have leading whitespace, not trailing whitespace</p></item>
+</list>
+
+</page>
diff --git a/gjs-style-guide/Makefile.am b/gjs-style-guide/Makefile.am
new file mode 100644
index 0000000..3c39713
--- /dev/null
+++ b/gjs-style-guide/Makefile.am
@@ -0,0 +1,16 @@
+ YELP_HELP_RULES@
+
+HELP_ID = gjs-style-guide
+
+HELP_FILES = \
+       declarations.page \
+       general.page \
+       gobject-concepts.page \
+       index.page \
+       variables.page \
+       whitespace.page \
+       legal.xml
+
+HELP_MEDIA =
+
+HELP_LINGUAS =
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]