-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
210 lines (202 loc) · 20.9 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>zvint's sass code guidelines</title>
<link rel="stylesheet" href="https://stackedit.io/style.css" />
</head>
<body class="stackedit">
<div class="stackedit__left">
<div class="stackedit__toc">
<ul>
<li><a href="#introduction">Introduction</a>
<ul>
<li><a href="#clarification-and-good-to-know">Clarification and good to know</a></li>
</ul>
</li>
<li><a href="#naming-conventions">1 - Naming conventions</a>
<ul>
<li><a href="#functions-and-mixins">1.1 - Functions and mixins</a></li>
<li><a href="#variables">1.2 - Variables</a></li>
<li><a href="#module-namespaces">1.3 - Module namespaces</a></li>
</ul>
</li>
<li><a href="#code-style">2 - Code style</a>
<ul>
<li><a href="#any-syntax">2.1 - Any syntax</a></li>
<li><a href="#scss-syntax">2.2 - SCSS syntax</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="stackedit__right">
<div class="stackedit__html">
<p><strong>zvint’s sass code guidelines</strong></p>
<h1 id="introduction">Introduction</h1>
<p><em><strong>Sass</strong></em> is a relatively small but extremely powerful scripting language in order to style web components. It is also very popular, which makes up for a lot of diversity, especially when it comes to whether one should even use a CSS preprocessor or opt-in for alternatives (like CSS in JS).</p>
<p>If you are one of the majority of people that like having separation of concerns by dividing your <em>app</em> and <em>style</em>, it must be understood that it is as important to have conventions for the code of your <em>app</em>, as well as for your <em>styling</em>. Having inconsistent code-styles may not harm or interest your workflow, but it helps a ton when collaborating with others - and also if you come back later to inspect your old code.</p>
<p>These guidelines, as simple as they seem, will speed up your efficiency, help you to find bugs significantly and make your code look better. Well, let’s get into it, shall we?</p>
<h2 id="clarification-and-good-to-know">Clarification and good to know</h2>
<p><em><strong>Does this guide have opinions about CSS?</strong></em></p>
<blockquote>
<p>This guideline has no explicit opinion about CSS. It is primarily opinionated about Sass and only contains a few points that also apply to CSS in Sass.</p>
</blockquote>
<p><em><strong>Is this guide about SCSS or Sass?</strong></em></p>
<blockquote>
<p>This document contains guidelines for Sass and SCSS. SCSS and “the indented syntax” are understood under “Sass” and it is explicitly mentioned if only SCSS or “the indented syntax” is targeted.</p>
</blockquote>
<p><em><strong>What syntax is preferred?</strong></em></p>
<blockquote>
<p>SCSS. The examples in this guide are all written in the SCSS syntax. Please refer to the official <a href="https://sass-lang.com/documentation/syntax#the-indented-syntax">Sass syntax docs</a> to learn how to translate the examples to the indented syntax.</p>
</blockquote>
<h1 id="naming-conventions">1 - Naming conventions</h1>
<p>Naming conventions give us a lot of advantages and are necessary when it comes to modern day software development. Naming conventions give us consistency, help us debug our code and help us use and name things, which, as we all know, is the hardest part of programming.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token variable">$_fooBar</span> <span class="token variable">$pFooBar</span> <span class="token variable">$fooBar</span> <span class="token variable">$_FooBar</span> <span class="token variable">$_FOO_BAR</span> _foo_<span class="token function">bar</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token function">foo-bar</span><span class="token punctuation">(</span><span class="token punctuation">)</span> foo_bar
</code></pre>
<p>Jokes aside, you will be able to intuitively recognize and distinguish the usages of every item in the example above after understanding the following conventions.</p>
<h2 id="functions-and-mixins">1.1 - Functions and mixins</h2>
<p>Since there already is a language-specific distinction between a <em>mixin</em> and <em>function</em>, both are named the same way. Although both are named with the same schema, there is a (also native) distinction between a private and public function or mixin.</p>
<blockquote>
<p>The reason we separate the naming convention of private and public functions and mixins is to immediately show the user a distinct difference in their visibility.</p>
</blockquote>
<h3 id="public-functions-and-mixins">1.1.1 - <em>Public</em> functions and mixins</h3>
<p>Functions that are accessible publicly are written in lower <code>kebab-case</code>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token keyword">@function</span> <span class="token function">my-public-function</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
<span class="token comment">// or as a mixin</span>
<span class="token keyword">@mixin</span> <span class="token function">my-public-mixin</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre>
<h3 id="private-functions-and-mixins">1.1.2 - <em>Private</em> functions and mixins</h3>
<p>Functions and mixins that are supposed to be private are prefixed with an underscore (<code>_</code>), followed by lower <code>snake_case</code>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token keyword">@function</span> my_private_<span class="token function">function</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
<span class="token comment">// or as a mixin</span>
<span class="token keyword">@mixin</span> _my_private_<span class="token function">mixin</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre>
<h2 id="variables">1.2 - Variables</h2>
<h3 id="parameters">1.2.1 - Parameters</h3>
<p>Every parameter that is <em>not</em> a variable-argument is prefixed with <code>p</code> followed by <code>PascalCase</code>,</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token keyword">@function</span> <span class="token function">my-function</span><span class="token punctuation">(</span><span class="token variable">$pFoo</span>, <span class="token variable">$pBar</span><span class="token punctuation">)</span>
</code></pre>
<p>whereas a variable-argument is prefixed with <code>va</code> and also followed by <code>PascalCase</code>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token keyword">@function</span> <span class="token function">my-function</span><span class="token punctuation">(</span><span class="token variable">$vaFooBars</span><span class="token number">...</span><span class="token punctuation">)</span>
</code></pre>
<h3 id="locals">1.2.2 - Locals</h3>
<p>A locally declared variable that is <em>not</em> a parameter is prefixed with an underscore (<code>_</code>) and followed by <code>camelCase</code>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token comment">// ... local scope</span>
<span class="token property"><span class="token variable">$_localVariable</span></span><span class="token punctuation">:</span> fooBaz<span class="token punctuation">;</span>
</code></pre>
<h3 id="public-globals">1.2.3 - <em>Public</em> globals</h3>
<p>Globally declared variables have two general ways to be written.</p>
<p><strong>Variant 1: style-specific globals</strong><br>
A global variable that can be applied to a css-property <em>and</em> is intended to be style-specific is written in <code>kebab-case</code>, using a hyphen (<code>-</code>) to indicate its private accessibility.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$background-color</span></span><span class="token punctuation">:</span> red<span class="token punctuation">;</span>
<span class="token property"><span class="token variable">$-background-color</span></span><span class="token punctuation">:</span> blue<span class="token punctuation">;</span>
</code></pre>
<p>Keeps it consistent with <a href="#public-functions-and-mixins"><em>public</em></a>- and different with <a href="#private-functions-and-mixins"><em>private</em></a> functions and mixins. This also is compliant with most css namings and helps users to understand the styling-purpose.</p>
<p><strong>Variant 2: non-style-specific globals</strong><br>
A global variable that is <em><strong>not</strong></em> applicable to a css-property <em>or</em> not intended to be style-specific is written differently depending on its accessibility.</p>
<p>A <em>public</em> not style-specific global is written in <code>camelCase</code>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$myPublicGlobalMap</span></span><span class="token punctuation">:</span> <span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre>
<p>A <em>private</em> not style-specific global is written in <code>PascalCase</code> with an underscore (<code>_</code>) indicating its private accessibility.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$_MyPrivateGlobalMap</span></span><span class="token punctuation">:</span> <span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre>
<p><strong>Conclusion of both variants</strong><br>
Both variants are really useful to immediately show a user the purpose and intention of a global. Global variables that are meant for a sole style purpose are treated differently to variables that have no initial intention for styling or cannot be applied to a css-property directly.</p>
<h3 id="global-private-constants">1.2.4 - Global <em>private</em> constants</h3>
<p>If a <em>privately</em> declared global is meant to be a constant, it is written in upper <code>SNAKE_CASE</code>. The variable may <em>not</em> be reassigned after the variable is declared once.</p>
<blockquote>
<p>⚠️ There is no physical constness as of <code>Dart Sass 1.57</code>, so there is no guarantee a variable is never modified after its initial declaration. It just serves as a recommendation.</p>
</blockquote>
<p>This convention really is only applicable if a global is <em>private</em>, since any external<br>
acquiring the variable may override or oversee the intended logical constness.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token comment">// ... global scope</span>
<span class="token property"><span class="token variable">$_GLOBAL_PRIVATE_CONSTANT</span></span><span class="token punctuation">:</span> fooBar<span class="token punctuation">;</span>
</code></pre>
<h2 id="module-namespaces">1.3 - Module namespaces</h2>
<p>The namespace of a module must always be in <code>snake_case</code>. Since the namespace of a module is implicitly its filename without extension*, the casing also applies for the name of every file that is intended to be used as a Sass module in other style files.</p>
<p>The above convention also applies for when you define an explicit namespace using an import statement such as <a href="https://sass-lang.com/documentation/at-rules/use#choosing-a-namespace"><code>@use <url> as <namespace></code></a>, where the implicit namespace is replaced by the explicit for the scope it is imported in.</p>
<p><em><code>*</code> By default, a module’s namespace is just the last component of its URL without a file extension</em></p>
<h1 id="code-style">2 - Code style</h1>
<h2 id="any-syntax">2.1 - Any syntax</h2>
<p>This section provides code-style conventions for both Sass syntaxes.</p>
<h3 id="character-limit">2.1.1 - Character limit</h3>
<p>Every line has a maximum character limit of 95.</p>
<h3 id="parameter-limit">2.1.2 - Parameter limit</h3>
<p>The maximum number of parameters is indefinite, but from a visual perspective a function or mixin should not have more than 6 (six) individually named parameters in its signature.<br>
If your code requires you to pass more parameters than is recommended, reconsider your implementation.</p>
<h3 id="quotation-marks">2.1.3 - Quotation marks</h3>
<p>If a string that is <em>not</em> a URL contains no whitespace character, it is wrapped in single-quotes (<code>'...'</code>). Otherwise, a string is wrapped in double-quotes (<code>"..."</code>).</p>
<blockquote>
<p>Imports are done with double-quotes, since they use a URL.</p>
</blockquote>
<pre class=" language-scss"><code class="prism language-scss">@use <span class="token string">"foo_bar"</span> as baz_qux<span class="token punctuation">;</span>
<span class="token property"><span class="token variable">$sentence</span></span><span class="token punctuation">:</span> <span class="token string">"hello world"</span><span class="token punctuation">;</span>
<span class="token property"><span class="token variable">$word</span></span><span class="token punctuation">:</span> <span class="token string">'fooBar'</span><span class="token punctuation">;</span>
</code></pre>
<p>If a string contains interpolation but no whitespace character, single-quotes are used, even if the interpolation contains whitespace.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$sentenceWithPeriod</span></span><span class="token punctuation">:</span> <span class="token string">'#{$sentence}.'</span><span class="token punctuation">;</span>
</code></pre>
<h2 id="scss-syntax">2.2 - SCSS syntax</h2>
<h3 id="indentation">2.2.1 - Indentation</h3>
<p>Each substatement of a statement should be indented by 2 (two) whitespace characters.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token keyword">@if</span> <span class="token punctuation">(</span>foo<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>bar<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token comment">// ...</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre>
<h3 id="line-wrap">2.2.2 - Line wrap</h3>
<p><strong>Line wrap for maps</strong><br>
In a map with more than 2 (two) key-value pairs, each key-value pair should be put on their own line followed by a comma at the end of each line, except for the last key-value pair.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$someGlobalMap</span></span><span class="token punctuation">:</span> <span class="token punctuation">(</span>
<span class="token property">hello</span><span class="token punctuation">:</span> world,
<span class="token property">foo</span><span class="token punctuation">:</span> bar,
<span class="token property">baz</span><span class="token punctuation">:</span> qux
<span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre>
<p><strong>Line wrap for lists</strong><br>
In a list with more than 5 (five) elements, insert a newline character followed by the necessary <a href="#indentation">indentation</a> every five elements, or at whenever the line length would exceed the specified <a href="#character-limit">character limit</a>.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token property"><span class="token variable">$someGlobalList</span></span><span class="token punctuation">:</span> <span class="token punctuation">(</span>
<span class="token string">"foo"</span>, <span class="token string">"bar"</span>, <span class="token string">"foobar"</span>, <span class="token string">"baz"</span>, <span class="token string">"qux"</span>,
<span class="token string">"quux"</span>, <span class="token string">"lorem"</span>, <span class="token string">"dolor"</span>, <span class="token string">"hello"</span>, <span class="token string">"world"</span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre>
<p>Although this usage of list-wrapping is recommended, it is pretty loose, so you don’t have to follow this one-to-one in order to follow this guideline.</p>
<h3 id="nesting">2.2.3 - Nesting</h3>
<p>There must not be more than 4 (four) nested scopes.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token comment">// ⚠️ BAD:</span>
<span class="token selector">.selector </span><span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>!foo<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>!bar<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>!baz<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>!qux<span class="token punctuation">)</span> <span class="token punctuation">{</span> <span class="token comment">// <-- too much </span>
<span class="token comment">// ...</span>
<span class="token comment">// ✅ GOOD:</span>
<span class="token selector">.selector </span><span class="token punctuation">{</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>!foo <span class="token operator">and</span> !bar <span class="token operator">and</span> !baz <span class="token operator">and</span> !qux<span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token comment">// or:</span>
<span class="token keyword">@if</span> <span class="token punctuation">(</span>not <span class="token punctuation">(</span>foo <span class="token operator">or</span> bar <span class="token operator">or</span> baz <span class="token operator">or</span> qux<span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token comment">// ...</span>
</code></pre>
<h3 id="semicolon">2.2.4 - Semicolon</h3>
<p>If a semicolon can be placed after a statement, it shall be done. More formally, every statement that is not a control flow statement (<em>i.e. end with a scope</em>) must end with a semicolon (<code>;</code>) and a newline character.</p>
<pre class=" language-scss"><code class="prism language-scss"><span class="token comment">// ⚠️ BAD:</span>
<span class="token keyword">@function</span> <span class="token function">my-function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@return</span> <span class="token string">'myValue'</span>
<span class="token punctuation">}</span>
<span class="token comment">// ✅ GOOD:</span>
<span class="token keyword">@function</span> <span class="token function">my-function</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">@return</span> <span class="token string">'myValue'</span><span class="token punctuation">;</span>
<span class="token comment">// ^</span>
<span class="token punctuation">}</span>
</code></pre>
<p><strong>Why?</strong> It makes your code more consistent, easier to read, debug and maintain.</p>
<hr>
<p>Well that’s a wrap! I hope you like this guideline.<br>
If you have suggestions you can DM me on Discord: <strong>@boned#0937</strong></p>
</div>
</div>
</body>
</html>