mirror/sqlstyle.guide
1
0
Fork 0
mirror of https://github.com/treffynnon/sqlstyle.guide.git synced 2025-03-09 12:49:51 -05:00
Code Activity

Move to using a Markdown file for the guide

Browse source
This commit is contained in:
Simon Holywell 2015-07-06 12:30:19 +01:00
parent 6e2b85c8e4
commit 622b3b8c34
3 changed files with 1012 additions and 246 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

205
index.html
View file

@ -1,205 +0,0 @@
---
layout: default
---
<section class="row overview">
<div class="col">
<h2>Overview</h2>
<p>
You can use this set of guidelines, <a href="">fork 'em</a> or make your own - the
key here is that you pick a style and stick to it. To suggest changes
or fix bugs please open an <a href="">issue</a> or <a href="">pull request</a> on Git Hub.
</p>
</div>
<div class="col">
</div>
</section>
<div class="heading" id="general">
<h2>General</h2>
</div>
<section class="row">
<div class="col">
<h3>Avoid the use of</h3>
<ul>
<li>CamelCase—it is difficult to scan quickly</li>
<li>Descriptive prefixes or Hungarian notation such as <code>sp_</code> or <code>tbl</code></li>
<li>Plurals—use the more natural collective term instead</li>
<li>Quoted identifiers—if you must use them then stick to SQL92 double quotes for portability</li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<div class="heading" id="general">
<h2>Syntax</h2>
</div>
<section class="row">
<div class="col">
<h3>Reserved words</h3>
<p>Always use uppercase for the <a href="#keyword-reference">reserved keywords</a> like <code>SELECT</code> and <code>WHERE</code>.</p>
<p>It is best to avoid the abbreviated keywords and use the full length ones where available (prefer <code>ABSOLUTE</code> to <code>ABS</code>).</p>
<p>Do not use database server specific keywords where an ANSI SQL keyword already exists performing the same function. This helps to make code more portable.</p>
</div>
<div class="col">
{% highlight sql %}{% include sql/syntax_reserved_keywords.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Indentation</h3>
<p>Use four (4) spaces all the way through all the time. This makes the most sense where there is a sub query.</p>
</div>
<div class="col">
{% highlight sql %}{% include sql/syntax_indentation.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>White space</h3>
<p>To make the code easier to read it is important that the correct compliment of spaces is used. Do not crowd code or remove natural spaces.</p>
<p>Always include spaces (this is not an exhaustive list):</p>
<ul>
<li>before and after equals (<code>=</code>)</li>
<li>after commas (<code>,</code>)</li>
<li>surrounding apostrophes (<code>'</code>) where not within parentheses or with a trailing comma or semicolon</li>
</ul>
<p>Always include newlines/vertical space:</p>
<ul>
<li>after semicolons to separate queries for easier reading</li>
<li>after each keyword definition</li>
<li>after the comma of each column in the list</li>
<li>before <code>AND</code> or <code>OR</code>
</ul>
<p>Keeping all the keywords aligned to the righthand side and the values left aligned creates a uniform gap down the middle of query. It makes it much easier to scan the query definition over quickly too.</p>
</div>
<div class="col">
{% highlight sql %}{% include sql/syntax_spacing.sql %}{% endhighlight %}
</div>
</section>
<div class="heading" id="naming-conventions">
<h2>Naming conventions</h2>
</div>
<section class="row">
<div class="col">
<h3>General</h3>
<ul>
<li>Ensure the name is unique and does not exist as a <a href="#keyword-reference">reserved keyword</a></li>
<li>Keep the length to a maximum of 30 bytes—in practice this is 30 characters unless you are using multibyte charset</li>
<li>Names must begin with a letter and may not end with an underscore</li>
<li>Only use letters, numbers and underscores in names</li>
<li>Avoid the use of multiple consecutive underscores—these can be hard to read</li>
<li>Use underscores where you would naturally include a space in name (first name becomes <code>first_name</code>)<li>
<li>Avoid abbreviations and if you have to use them make sure they are commonly understood</li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Tables</h3>
<ul>
<li>Use a collective name or, less ideally, a plural form. For example (in order of preference) staff and employees.</li>
<li>Do not prefix with <code>tbl</code> or any other such descriptive prefix or Hungarian notation</li>
<li>Never give a table the same name as one of its columns</li>
<li>Avoid, where possible, concatenating two table names together to create the name of a relationship table. Rather than <code>car_mechanic</code> prefer <code>service</code></li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Columns</h3>
<ul>
<li>Always use the singular name</li>
<li>Avoid simply using <code>id</code> as the primary identifier for the table</li>
<li>Do not add a column with the same name as its table</li>
<li>Always use lowercase except where it may make sense not to such as proper nouns</li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Aliasing or correlations</h3>
<ul>
<li>Should relate in some way to the object or expression they are aliasing</li>
<li>As rule of thumb the correlation name should be the first letter of each word in the object's name</li>
<li>If there is already a correlation with same name then append a number</li>
<li>Always include the <code>AS</code> keyword—makes it easier to read as it is explicit</li>
<li>For computed data (<code>SUM()</code> or <code>AVG()</code>) use the name you would give it were it a column defined in the schema</li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_correlations.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Stored procedures</h3>
<ul>
<li>The name must contain a verb</li>
<li>Do not prefix with <code>sp_</code> or any other such descriptive prefix or Hungarian notation</li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<section class="row">
<div class="col">
<h3>Uniform postfixes</h3>
<ul>
<li><code>_id</code>—a unique identifier such as a column that is a primary key</li>
<li><code>_status</code>—flag value or some other status of any type such as <code>publication_status</code>
<li><code>_total</code>—the total or sum of a collection of values</li>
<li><code>_name</code>—signifies a name such as <code>first_name</code></li>
<li><code>_seq</code>—contains a contiguous sequence of values</li>
<li><code>_date</code>—denotes a column that contains the date of something</li>
<li><code>_tally</code>—a count</li>
<li><code>_size</code>—the size of something such as a file size or clothing</li>
<li><code>_addr</code>—an address for the record could be physical or intangible such as <code>ip_addr</code></li>
</ul>
</div>
<div class="col">
{% highlight sql %}{% include sql/naming_conventions.sql %}{% endhighlight %}
</div>
</section>
<div class="heading" id="appendices">
<h2>Appendices</h2>
</div>
<section class="row" id="keyword-reference">
<div class="col">
<h3>Reserved keyword reference</h3>
<p>A list of ANSI SQL 92, ANSI SQL 99, ANSI SQL 2003, MySQL 3.23.x, MySQL 4.x, MySQL 5.x, PostGreSQL 8.1, MS SQL Server 2000, MS ODBC, Oracle 10.2 reserved keywords.</p>
</div>
<div class="col">
{% highlight SQL %}{% include sql/appendices_reserved_keywords.sql %}{% endhighlight %}
</div>
</section>
<p>body of the site is here</p>
{% highlight sql %}{% include sql/test.sql %}{% endhighlight %}

1007
index.md Normal file
View file

File diff suppressed because it is too large Load diff

46
style.css
View file

@ -23,51 +23,15 @@ body {
color: #5a5a5a;
}
/*
* The Grid
*/
.col {
padding: 2rem 1rem;
}
.col p {
max-width: 40rem;
}
.col + .col {
border-top: 1px solid #dfe1e8;
background-color: #f7f7f9;
}
@media (min-width: 38em) {
.col {
padding: 2rem;
}
}
@media (min-width: 48em) {
.row {
display: table;
width: 100%;
table-layout: fixed;
}
.col {
display: table-cell;
padding: 3rem;
vertical-align: top;
}
.col + .col {
border-top: 0;
}
}
.row {
border-bottom: 1px solid #dfe1e8;
}
/*
End styles from codeguide.co by @mdo
*/
pre code {
max-height: 450px;
overflow-y: auto;
}
{% include highlight.hybrid.css %}