Permalink
Browse files

Initial commit of developer's pages.

  • Loading branch information...
arantius committed May 18, 2010
0 parents commit a724c1ecf1243099557ada7373dad7626be684b9
Showing with 133 additions and 0 deletions.
  1. +27 −0 contrib.html
  2. +12 −0 index.html
  3. +94 −0 style.html
@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<title>Contributing To Greasemonkey</title>
+</head>
+<body>
+<h1>Contributing To Greasemonkey</h1>
+
+<p>This document is a stub and should be improved.</p>
+
+<h2>Git</h2>
+<p>Greasemonkey source code is managed via Git. Git is a very different version control system, and you should learn how to use it.</p>
+
+<p>Links:</p>
+<ul>
+<li><a href="http://progit.org/">Pro Git</a></li>
+<li><a href="http://www.gitready.com/">Git Ready</a></li>
+</ul>
+
+<p>Most importantly, all independent changes should be isolated into separate branches. Any given branch should be clearly explained and proposed for inclusion in Greasemonkey via the <a href="http://groups.google.com/group/greasemonkey-dev">greasemonkey-dev mailing list</a>, or the <a href="http://github.com/greasemonkey/greasemonkey/issues">issue ticket</a> if there is an appropriate one.</p>
+
+<h2>Be Inclusive</h2>
+
+<p>Please include the entire development community when hacking on Greasemonkey. Discussion on the mailing list is highly encouraged. Discussion on the appropriate issue is often equally appropriate.</p>
+
+</body>
+</html>
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<title>Greasemonkey Developer Pages</title>
+</head>
+<body>
+<ul>
+<li><a href="style.html">Greasemonkey Programming Style Guide</a></li>
+<li><a href="contrib.html">Contributing To Greasemonkey</a></li>
+</ul>
+</body>
+</html>
@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<title>Greasemonkey - Programming Style Guide</title>
+<style type="text/css">
+pre {
+ background: none repeat scroll 0 0 #EEEEEE;
+ border: 1px dashed #666666;
+ display: block;
+ font-size: 1.1em;
+ line-height: 1.1em;
+ margin: 1ex;
+ overflow: auto;
+ padding: 1ex;
+ white-space: pre;
+}
+</style>
+</head>
+<body>
+<h1>Greasemonkey - JavaScript Style Guide</h1>
+<p>This document describes the JavaScript style for the Greasemonkey project. Below, use of the word "should" is only for its effect on the prose, and actually means "must".</p>
+<p>This guide is based on a Mozilla JavaScript Style Guide document which no longer exists (and was previously the Greasemonkey style guide), which in turn was based on a <a href='http://web.archive.org/web/20080328023013/http://web.archive.org/web/20080328023013/http://neil.rashbrook.org/Js.htm'>document by Niel Rashbrook</a>.</p>
+<h2>Whitespace</h2>
+<ul>
+<li>Indent blocks with two spaces. No tabs.</li>
+<li>Lines should be no longer than 80 characters.</li>
+<li>When breaking statements across multiple lines, continuation lines should be indented by four spaces.</li>
+<li>Surround binary operators with single spaces.</li>
+<li>Put a single space after keywords (if, for, etc).</li>
+<li>One (or two) blank lines between block definitions. Also consider breaking up large code blocks with blank lines.</li>
+<li>Files should contain exactly one newline at the end.</li>
+<li>Lines should have no trailing whitespace.</li>
+</ul>
+<h2>Symbols</h2>
+<ul>
+<li>Spaces around braces used for in-line functions or objects, except before commas or semicolons, e.g. <pre>function valueObject(aValue) { return { value: aValue }; }</pre></li>
+<li>Otherwise spaces are not necessary inside brackets.</li>
+<li>Prefer double quotes, except when quoting double quotes.</li>
+<li>Braces are not indented relative to their parent statement. Blocks should be indented as:<pre>if (dlmgrWindow) {
+ dlmgrWindow.focus();
+} else {
+ dlmgr.open(window, null);
+}</pre>
+Braces on if/else statements are not optional, unless the entire compound statement fits completely on one line.</li>
+</ul>
+<h2>Code Style</h2>
+<ul>
+<li>Always put else on its own line, as shown above. </li>
+<li>Name inline functions, this makes it easier to debug them. Just assigning a function to a property doesn't name the function, you should to do something like: <pre>var offlineObserver = {
+ observe: function OO_observe(aSubject, aTopic, aState) {
+ if (aTopic == "network:offline-status-changed")
+ setOfflineUI(aState == "offline");
+ }
+};</pre></li>
+</ul>
+<h2>Function and variable naming</h2>
+<ul>
+<li>Unless otherwise specified, use camelCasedNames.</li>
+<li>Constants should be in <code>UPPER_CASE</code>.</li>
+<li>Use InterCaps and capitalize the first letter of constructors.</li>
+<li>Do not pollute the global namespace. Objects and functions should use a <code>GM_</code> name prefix.</li>
+<li>Global variables should be prefixed with the letter g, e.g. gFormatToolbar.</li>
+<li>Arguments (parameter names) should be prefixed with the letter a.</li>
+<li>Private members should start with <code>_</code>, e.g. <code>_internalFunction</code>.</li>
+<li>Event handler functions should be prefixed with the word on, in particular try to use the names onLoad, onDialogAccept, onDialogCancel, etc., where this is unambiguous.</li>
+<li>Function names, local variables, and object members have no prefix.</li>
+<li>Try to declare local variables as near to their use as possible; try to initialize every variable.</li>
+</ul>
+<h2>JavaScript Features</h2>
+<ul>
+<li>Make sure that your code doesn't generate any strict JavaScript
+ warnings, such as:
+ <ul>
+ <li>Duplicate variable declaration</li>
+ <li> Mixing <code>return;</code> with <code>return value;</code></li>
+ <li> Trailing comma in JavaScript object declarations</li>
+ </ul>
+</li>
+<li>Use <code>[value1, value2]</code> to create a JavaScript array in preference to using new <code>Array(value1, value2)</code>.</li>
+<li>Use <code>{ member: value, ... }</code> to create a JavaScript object; over <code>new Object()</code>.</li>
+<li>Don't compare booleans to <code>true</code> or <code>false</code>. For example, write <code>if (ioService.offline)</code>. Compare objects to <code>null</code>, numbers to <code>0</code> or strings to <code>""</code> if there is chance for confusion.</li>
+</ul>
+<h2>Suggestions</h2>
+<p>These guidelines are not hard and fast rules, but almost always a good idea. Please try to follow them.</p>
+<ul>
+<li>Be very careful about assignments that are also used in a boolean context, e.g. <pre>while (node = node.parentNode) { /* ... */ }</pre> Try to avoid such usage, or carefully comment that testing the result of an assignment as a boolean is actually intended.</li>
+<li>When a <code>switch</code> statement's <code>case</code> contains a body, and intentionally falls through to the next (with no <code>break</code>), add a comment like <code>// fall-through</code> to make it clear that this is intended.</li>
+<li>Don't use <code>eval()</code> or equivalents if there is any other possible way to accomplish the goal.</li>
+<li>Don't use <code>setTimeout()</code> or equivalents with string parameters, only function references.</li>
+<li>Keep threads, and especially commits, topically relevant. Don't put code refactoring and new features together in one commit, or even together in a branch if at all possible.</li>
+</ul>
+</body>
+</html>

0 comments on commit a724c1e

Please sign in to comment.