Skip to content

Commit

Permalink
Initial commit of developer's pages.
Browse files Browse the repository at this point in the history
  • Loading branch information
@arantius
arantius committed May 18, 2010
0 parents commit a724c1e
Show file tree
Hide file tree
Showing 3 changed files with 133 additions and 0 deletions.
27 changes: 27 additions & 0 deletions contrib.html
Original file line number Diff line number Diff line change
@@ -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>
12 changes: 12 additions & 0 deletions index.html
Original file line number Diff line number Diff line change
@@ -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>
94 changes: 94 additions & 0 deletions style.html
Original file line number Diff line number Diff line change
@@ -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.