diff options
Diffstat (limited to 'thoughts/syntax')
| -rw-r--r-- | thoughts/syntax/my-worst-habit.html | 53 | ||||
| -rw-r--r-- | thoughts/syntax/random-python-idiosyncrasies.html | 140 |
2 files changed, 157 insertions, 36 deletions
diff --git a/thoughts/syntax/my-worst-habit.html b/thoughts/syntax/my-worst-habit.html new file mode 100644 index 0000000..7d7698b --- /dev/null +++ b/thoughts/syntax/my-worst-habit.html @@ -0,0 +1,53 @@ +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> +<head> + <meta charset="utf-8" /> + <meta name="generator" content="pandoc" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> + <title>my-worst-habit</title> + <style> + code{white-space: pre-wrap;} + span.smallcaps{font-variant: small-caps;} + span.underline{text-decoration: underline;} + div.column{display: inline-block; vertical-align: top; width: 50%;} + div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} + ul.task-list{list-style: none;} + </style> +</head> +<body> +<p>Overuse of parentheses, by far.</p> +<p>Why is this a bad thing? Parentheses, as read by most readers, tend to contain additional <em>superfluous</em> information when read. So naturally, the mind tends to pay less attention to what's inside (or at least my mind does). I also believe it represents some repressed psychological trauma, since a Professor once circled how many times I abused the double dash, "--", and I haven't quite felt comfortable using it since--unless it feels right.</p> +<p>The punctuation works in that last example, but relying on it leads to bad habits, and usually, sentences that droll on for far longer than welcome. Consider the following example from Naked Lunch:</p> +<pre><code>Doc Browbeck was party inna second part. A retired abortionist and junk +pusher (he was a veterinarian actually) recalled to service during the +manpower shortage. Well, Doc had been in the hospital kitchen all +morning goosing the nurses and tanking up on coal gas and Klim -- and +just before the operation he sneaked a double shot of nutmeg to nerve +himself up. + +(In England and especially in Edinburgh the citizens bubble coal gas +through Klim -- a horrible form of powdered milk tasting like rancid +chalk -- and pick up on the results. They hock everything to pay the +gas bill, and when the man comes around to shut it off for the +non-payment, you can hear their screams for miles. When a citizen is +sick from needing it he says "I got the klinks" or "That old stove +climbing up my back." + +Nutmeg. I quote from the author's article on narcotic drugs in the +British Journal of Addiction (see Appendix): "Convicts and sailors +sometimes have recourse to nutmeg. About a tablespoon is swallowed +with water. Result vaguely similar to marijuana with side effects of +headache and nausea. There are a number of narcotics of the nutmeg +family in use among the Indians of South America. They are usually +administered by sniffing a dried powder of the plant. The medicine +men take these noxious substances and go into convulsive states. Their +twitchings and mutterings are thought to have prophetic significance.")</code></pre> +<p>This is the only example I know that dares to put parentheses <em>and</em> a long quote within parentheses, unless we're counting math textbooks. In a way it works, since if information is ever <em>superfluous</em>, the history of sailors getting high on nutmeg fits that bill. A careful reader might easily pick up on that, but to everyone else, I think a full paragraph of text in parentheses signals the reader to scroll down in the hopes that the story continues.</p> +<p>But just in case you think I'm just picking on William S. Burroughs, here's an example I regrettably wrote to a coworker recently with some details removed:</p> +<pre><code>[...] As a precaution, I did review $NOBODY's recent +$THING_I_WAS_ASKED_TO_REVIEW (if you would like a detailed report on +that, I can pull that together for you).</code></pre> +<p>Somehow, I managed to take the <em>one</em> point worth emphasizing (an entire sentence at that!) and <em>de</em>-emphasized it.</p> +<p>It's a habit I can't break. So please, if you are a caring reader, do complain when I overuse parentheses. I deserve it.</p> +</body> +</html> diff --git a/thoughts/syntax/random-python-idiosyncrasies.html b/thoughts/syntax/random-python-idiosyncrasies.html index 80e4563..ba88071 100644 --- a/thoughts/syntax/random-python-idiosyncrasies.html +++ b/thoughts/syntax/random-python-idiosyncrasies.html @@ -12,6 +12,68 @@ div.column{display: inline-block; vertical-align: top; width: 50%;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} ul.task-list{list-style: none;} + pre > code.sourceCode { white-space: pre; position: relative; } + pre > code.sourceCode > span { display: inline-block; line-height: 1.25; } + pre > code.sourceCode > span:empty { height: 1.2em; } + code.sourceCode > span { color: inherit; text-decoration: inherit; } + div.sourceCode { margin: 1em 0; } + pre.sourceCode { margin: 0; } + @media screen { + div.sourceCode { overflow: auto; } + } + @media print { + pre > code.sourceCode { white-space: pre-wrap; } + pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; } + } + pre.numberSource code + { counter-reset: source-line 0; } + pre.numberSource code > span + { position: relative; left: -4em; counter-increment: source-line; } + pre.numberSource code > span > a:first-child::before + { content: counter(source-line); + position: relative; left: -1em; text-align: right; vertical-align: baseline; + border: none; display: inline-block; + -webkit-touch-callout: none; -webkit-user-select: none; + -khtml-user-select: none; -moz-user-select: none; + -ms-user-select: none; user-select: none; + padding: 0 4px; width: 4em; + color: #aaaaaa; + } + pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } + div.sourceCode + { } + @media screen { + pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; } + } + code span.al { color: #ff0000; font-weight: bold; } /* Alert */ + code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ + code span.at { color: #7d9029; } /* Attribute */ + code span.bn { color: #40a070; } /* BaseN */ + code span.bu { } /* BuiltIn */ + code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ + code span.ch { color: #4070a0; } /* Char */ + code span.cn { color: #880000; } /* Constant */ + code span.co { color: #60a0b0; font-style: italic; } /* Comment */ + code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ + code span.do { color: #ba2121; font-style: italic; } /* Documentation */ + code span.dt { color: #902000; } /* DataType */ + code span.dv { color: #40a070; } /* DecVal */ + code span.er { color: #ff0000; font-weight: bold; } /* Error */ + code span.ex { } /* Extension */ + code span.fl { color: #40a070; } /* Float */ + code span.fu { color: #06287e; } /* Function */ + code span.im { } /* Import */ + code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ + code span.kw { color: #007020; font-weight: bold; } /* Keyword */ + code span.op { color: #666666; } /* Operator */ + code span.ot { color: #007020; } /* Other */ + code span.pp { color: #bc7a00; } /* Preprocessor */ + code span.sc { color: #4070a0; } /* SpecialChar */ + code span.ss { color: #bb6688; } /* SpecialString */ + code span.st { color: #4070a0; } /* String */ + code span.va { color: #19177c; } /* Variable */ + code span.vs { color: #4070a0; } /* VerbatimString */ + code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </style> </head> <body> @@ -22,64 +84,70 @@ <ul> <li><a href="#strings-are-double-quoted.-keys-and-chars-are-single-quoted.">1) <em>Strings</em> are <em>double-quoted</em>. <em>Keys</em> and <em>chars</em> are <em>single-quoted</em>.</a></li> <li><a href="#long-strings-belong-in-parentheses">2) Long strings belong in parentheses</a></li> -<li><a href="#tabs-are-four-spaces-and-spaces-are-always-prefered-to-tabs">3) Tabs are four spaces and spaces are <em>ALWAYS</em> prefered to tabs</a></li> +<li><a href="#tabs-are-four-spaces-and-spaces-are-always-preferred-to-tabs">3) Tabs are four spaces and spaces are <em>ALWAYS</em> preferred to tabs</a></li> <li><a href="#always-add-spaces-between-arithmetic-but-never-for-brackets">4) Always add spaces between arithmetic, but never for brackets</a></li> <li><a href="#everything-should-be-snake_case">5) EVERYTHING should be snake_case</a></li> </ul></li> </ul> </nav> <h1 id="coding-style-guide">Coding Style Guide</h1> -<p>The purpose of this document is twofold: 1) To ensure that anyone who might like to make my code better understands why I write python the way I do 2) to ensure <em>I</em> adhere to my own style because I'm terribly inconsistent</p> +<p>The purpose of this document is twofold:</p> +<ol type="1"> +<li>To ensure that anyone who might like to make my code better understands why I write python the way I do</li> +<li>To ensure <em>I</em> adhere to my own style because I'm terribly inconsistent</li> +</ol> <p>Being terribly inconsistent, the guidelines are not set in stone and if you have a good argument for doing things a particular, I don't really care.</p> -<p><em>BUT</em> first and foremost, <em>code must comply with PEP8 first</em>. This is easy to automate. I like coala since it's friendly but there' plenty of advanced linters out there.</p> +<p><em>BUT</em> first and foremost, <em>code must comply with PEP8 first</em>. This is easy to automate. I like <a href="https://pypi.org/project/black/">black</a> since it's easy to use but there' plenty of advanced linters out there.</p> +<p>I usually invoke it like this to turn off forcing double quotes and force the line length to 72:</p> +<div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true"></a><span class="ex">black</span> -S -l 72 file.py</span></code></pre></div> <p>That aside, I have the following idiosyncracies:</p> <h2 id="strings-are-double-quoted.-keys-and-chars-are-single-quoted.">1) <em>Strings</em> are <em>double-quoted</em>. <em>Keys</em> and <em>chars</em> are <em>single-quoted</em>.</h2> <p>This is really just because I like how C does it. And Cpython's C-based so why not?</p> <p>Like so:</p> -<pre class="code"><code>string = "This is a phrase" -word = "word" -cur_char = 'a' -newline = '\n' # note, two characters, but it's still ONE char out -# keys are single-quoted to avoid confusion -dictionary = { 'key' "1245dqw3w431", 'return': newline }</code></pre> +<div class="sourceCode" id="cb2"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true"></a>string <span class="op">=</span> <span class="st">"This is a phrase"</span></span> +<span id="cb2-2"><a href="#cb2-2" aria-hidden="true"></a>word <span class="op">=</span> <span class="st">"word"</span></span> +<span id="cb2-3"><a href="#cb2-3" aria-hidden="true"></a>cur_char <span class="op">=</span> <span class="st">'a'</span></span> +<span id="cb2-4"><a href="#cb2-4" aria-hidden="true"></a>newline <span class="op">=</span> <span class="st">'</span><span class="ch">\n</span><span class="st">'</span> <span class="co"># note, two characters, but it's still ONE char out</span></span> +<span id="cb2-5"><a href="#cb2-5" aria-hidden="true"></a><span class="co"># keys are single-quoted to avoid confusion</span></span> +<span id="cb2-6"><a href="#cb2-6" aria-hidden="true"></a>dictionary <span class="op">=</span> { <span class="st">'key'</span> <span class="st">"1245dqw3w431"</span>, <span class="st">'return'</span>: newline }</span></code></pre></div> <p>The only exception is for strings with quotes in them (anything to avoid escapes, really)</p> -<pre class="code"><code>quoted_string = ( - '"You miss 100% of the shots you don't take - Wayne Gretsky"' - ' - Michael Scott' -)</code></pre> +<div class="sourceCode" id="cb3"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true"></a>quoted_string <span class="op">=</span> (</span> +<span id="cb3-2"><a href="#cb3-2" aria-hidden="true"></a> <span class="st">'"You miss 100</span><span class="sc">% o</span><span class="st">f the shots you don'</span>t take <span class="op">-</span> Wayne Gretsky<span class="st">"'</span></span> +<span id="cb3-3"><a href="#cb3-3" aria-hidden="true"></a><span class="st"> ' - Michael Scott'</span></span> +<span id="cb3-4"><a href="#cb3-4" aria-hidden="true"></a><span class="st">)</span></span></code></pre></div> <p>That brings me to my next point.</p> <h2 id="long-strings-belong-in-parentheses">2) Long strings belong in parentheses</h2> <p>As in:</p> -<pre class="code"><code>longboi = ( - "This is a really long string usefull when making help menus. Be\n" - "sure to leave s space at the end of each line, or add a new line\n" - "when needed.\n\n" - - "Try your best to keep formatting accurate like this." -)</code></pre> -<h2 id="tabs-are-four-spaces-and-spaces-are-always-prefered-to-tabs">3) Tabs are four spaces and spaces are <em>ALWAYS</em> prefered to tabs</h2> +<div class="sourceCode" id="cb4"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a>longboi <span class="op">=</span> (</span> +<span id="cb4-2"><a href="#cb4-2" aria-hidden="true"></a> <span class="st">"This is a really long string usefull when making help menus. Be</span><span class="ch">\n</span><span class="st">"</span></span> +<span id="cb4-3"><a href="#cb4-3" aria-hidden="true"></a> <span class="st">"sure to leave s space at the end of each line, or add a new line</span><span class="ch">\n</span><span class="st">"</span></span> +<span id="cb4-4"><a href="#cb4-4" aria-hidden="true"></a> <span class="st">"when needed.</span><span class="ch">\n\n</span><span class="st">"</span></span> +<span id="cb4-5"><a href="#cb4-5" aria-hidden="true"></a></span> +<span id="cb4-6"><a href="#cb4-6" aria-hidden="true"></a> <span class="st">"Try your best to keep formatting accurate like this."</span></span> +<span id="cb4-7"><a href="#cb4-7" aria-hidden="true"></a>)</span></code></pre></div> +<h2 id="tabs-are-four-spaces-and-spaces-are-always-preferred-to-tabs">3) Tabs are four spaces and spaces are <em>ALWAYS</em> preferred to tabs</h2> <p>Again, see PEP8.</p> <h2 id="always-add-spaces-between-arithmetic-but-never-for-brackets">4) Always add spaces between arithmetic, but never for brackets</h2> <p>It's a pain to read:</p> -<pre class="code"><code>1/(2*sqrt(pi))*exp(x**2)</code></pre> +<div class="sourceCode" id="cb5"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true"></a><span class="dv">1</span><span class="op">/</span>(<span class="dv">2</span><span class="op">*</span>sqrt(pi))<span class="op">*</span>exp(x<span class="op">**</span><span class="dv">2</span>)</span></code></pre></div> <p>Do this</p> -<pre class="code"><code>1 / (2 * sqrt(pi)) * exp(x ** 2)</code></pre> +<div class="sourceCode" id="cb6"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true"></a><span class="dv">1</span> <span class="op">/</span> (<span class="dv">2</span> <span class="op">*</span> sqrt(pi)) <span class="op">*</span> exp(x <span class="op">**</span> <span class="dv">2</span>)</span></code></pre></div> <p>The same goes for logic operators</p> -<pre class="code"><code>true & false ^ true</code></pre> +<div class="sourceCode" id="cb7"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true"></a>true <span class="op">&</span> false <span class="op">^</span> true</span></code></pre></div> <h2 id="everything-should-be-snake_case">5) EVERYTHING should be snake_case</h2> <p>This is python. Unless there's a compatibility thing (like a library's code was written that way, or it matches an API variable), snake_case is preferred.</p> -<pre class="code"><code>user_input = int(input()) # variable -MAX_INPUT = 1000 # constant -def judge_input(_input, _max): # function - if _max > _input: - print("Too big!") - -judge_input(user_input, MAX_INPUT -class Input_Judger: # a class - # etc etc</code></pre> +<div class="sourceCode" id="cb8"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true"></a>user_input <span class="op">=</span> <span class="bu">int</span>(<span class="bu">input</span>()) <span class="co"># variable</span></span> +<span id="cb8-2"><a href="#cb8-2" aria-hidden="true"></a>MAX_INPUT <span class="op">=</span> <span class="dv">1000</span> <span class="co"># constant</span></span> +<span id="cb8-3"><a href="#cb8-3" aria-hidden="true"></a><span class="kw">def</span> judge_input(_input, _max): <span class="co"># function</span></span> +<span id="cb8-4"><a href="#cb8-4" aria-hidden="true"></a> <span class="cf">if</span> _max <span class="op">></span> _input:</span> +<span id="cb8-5"><a href="#cb8-5" aria-hidden="true"></a> <span class="bu">print</span>(<span class="st">"Too big!"</span>)</span> +<span id="cb8-6"><a href="#cb8-6" aria-hidden="true"></a></span> +<span id="cb8-7"><a href="#cb8-7" aria-hidden="true"></a>judge_input(user_input, MAX_INPUT</span> +<span id="cb8-8"><a href="#cb8-8" aria-hidden="true"></a><span class="kw">class</span> Input_Judger: <span class="co"># a class</span></span> +<span id="cb8-9"><a href="#cb8-9" aria-hidden="true"></a> <span class="co"># etc etc</span></span></code></pre></div> <p>Example exception:</p> -<pre class="code"><code># this doesn't actually work, but you get the idea -r = requests.get("www.debian.org") -pageSize = r.json()['pageSize'] # camel case ok</code></pre> +<div class="sourceCode" id="cb9"><pre class="sourceCode python"><code class="sourceCode python"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true"></a><span class="co"># this doesn't actually work, but you get the idea</span></span> +<span id="cb9-2"><a href="#cb9-2" aria-hidden="true"></a>r <span class="op">=</span> requests.get(<span class="st">"www.debian.org"</span>)</span> +<span id="cb9-3"><a href="#cb9-3" aria-hidden="true"></a>pageSize <span class="op">=</span> r.json()[<span class="st">'pageSize'</span>] <span class="co"># camel case ok</span></span></code></pre></div> </body> </html> |