diff --git a/.cache/plugin/social/15dff6182298aed7c82d46027d313295.png b/.cache/plugin/social/15dff6182298aed7c82d46027d313295.png
new file mode 100644
index 0000000..ca6e538
Binary files /dev/null and b/.cache/plugin/social/15dff6182298aed7c82d46027d313295.png differ
diff --git a/.cache/plugin/social/3826597e7f2e5b9a62b169e955c0158c.png b/.cache/plugin/social/3826597e7f2e5b9a62b169e955c0158c.png
new file mode 100644
index 0000000..cb7edad
Binary files /dev/null and b/.cache/plugin/social/3826597e7f2e5b9a62b169e955c0158c.png differ
diff --git a/.cache/plugin/social/3bf04759bea4f4cdfebcc3be6ddc8fc4.png b/.cache/plugin/social/3bf04759bea4f4cdfebcc3be6ddc8fc4.png
new file mode 100644
index 0000000..e039f27
Binary files /dev/null and b/.cache/plugin/social/3bf04759bea4f4cdfebcc3be6ddc8fc4.png differ
diff --git a/.cache/plugin/social/718ad6d76b7ec27c655c57e2bd49c9b6.png b/.cache/plugin/social/718ad6d76b7ec27c655c57e2bd49c9b6.png
new file mode 100644
index 0000000..1e105c7
Binary files /dev/null and b/.cache/plugin/social/718ad6d76b7ec27c655c57e2bd49c9b6.png differ
diff --git a/.cache/plugin/social/74b65d1b8fc534e7a28d9dff124e599b.png b/.cache/plugin/social/74b65d1b8fc534e7a28d9dff124e599b.png
new file mode 100644
index 0000000..b00f0a3
Binary files /dev/null and b/.cache/plugin/social/74b65d1b8fc534e7a28d9dff124e599b.png differ
diff --git a/.cache/plugin/social/Roboto-Black.ttf b/.cache/plugin/social/Roboto-Black.ttf
new file mode 100644
index 0000000..0112e7d
Binary files /dev/null and b/.cache/plugin/social/Roboto-Black.ttf differ
diff --git a/.cache/plugin/social/Roboto-BlackItalic.ttf b/.cache/plugin/social/Roboto-BlackItalic.ttf
new file mode 100644
index 0000000..b2c6aca
Binary files /dev/null and b/.cache/plugin/social/Roboto-BlackItalic.ttf differ
diff --git a/.cache/plugin/social/Roboto-Bold.ttf b/.cache/plugin/social/Roboto-Bold.ttf
new file mode 100644
index 0000000..43da14d
Binary files /dev/null and b/.cache/plugin/social/Roboto-Bold.ttf differ
diff --git a/.cache/plugin/social/Roboto-BoldItalic.ttf b/.cache/plugin/social/Roboto-BoldItalic.ttf
new file mode 100644
index 0000000..bcfdab4
Binary files /dev/null and b/.cache/plugin/social/Roboto-BoldItalic.ttf differ
diff --git a/.cache/plugin/social/Roboto-Italic.ttf b/.cache/plugin/social/Roboto-Italic.ttf
new file mode 100644
index 0000000..1b5eaa3
Binary files /dev/null and b/.cache/plugin/social/Roboto-Italic.ttf differ
diff --git a/.cache/plugin/social/Roboto-Light.ttf b/.cache/plugin/social/Roboto-Light.ttf
new file mode 100644
index 0000000..e7307e7
Binary files /dev/null and b/.cache/plugin/social/Roboto-Light.ttf differ
diff --git a/.cache/plugin/social/Roboto-LightItalic.ttf b/.cache/plugin/social/Roboto-LightItalic.ttf
new file mode 100644
index 0000000..2d277af
Binary files /dev/null and b/.cache/plugin/social/Roboto-LightItalic.ttf differ
diff --git a/.cache/plugin/social/Roboto-Medium.ttf b/.cache/plugin/social/Roboto-Medium.ttf
new file mode 100644
index 0000000..ac0f908
Binary files /dev/null and b/.cache/plugin/social/Roboto-Medium.ttf differ
diff --git a/.cache/plugin/social/Roboto-MediumItalic.ttf b/.cache/plugin/social/Roboto-MediumItalic.ttf
new file mode 100644
index 0000000..fc36a47
Binary files /dev/null and b/.cache/plugin/social/Roboto-MediumItalic.ttf differ
diff --git a/.cache/plugin/social/Roboto-Regular.ttf b/.cache/plugin/social/Roboto-Regular.ttf
new file mode 100644
index 0000000..ddf4bfa
Binary files /dev/null and b/.cache/plugin/social/Roboto-Regular.ttf differ
diff --git a/.cache/plugin/social/Roboto-Thin.ttf b/.cache/plugin/social/Roboto-Thin.ttf
new file mode 100644
index 0000000..2e0dee6
Binary files /dev/null and b/.cache/plugin/social/Roboto-Thin.ttf differ
diff --git a/.cache/plugin/social/Roboto-ThinItalic.ttf b/.cache/plugin/social/Roboto-ThinItalic.ttf
new file mode 100644
index 0000000..084f9c0
Binary files /dev/null and b/.cache/plugin/social/Roboto-ThinItalic.ttf differ
diff --git a/docs/chinese/presentation.md b/docs/chinese/index.md
similarity index 100%
rename from docs/chinese/presentation.md
rename to docs/chinese/index.md
diff --git a/docs/index.md b/docs/index.md
index 52b9fc6..250e21c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,15 +1,19 @@
 # 📖 Book Presentation
 
-Source code and community space of 📖 _100 Go Mistakes and How to Avoid Them_, published by Manning in August 2022.
+Source code and community space of _100 Go Mistakes and How to Avoid Them_, published by Manning in 2022.
+
+![](cover.png)
 
 ## Book Description
 
 If you're a Go developer looking to improve your skills, this book is for you. With a focus on practical examples, _100 Go Mistakes and How to Avoid Them_ covers a wide range of topics from concurrency and error handling to testing and code organization. You'll learn to write more idiomatic, efficient, and maintainable code and become a proficient Go developer.
 
-![](cover.png)
-
 ### Quotes
 
+> This is an exceptional book. Usually, if a book contains either high-quality explanations or is written succinctly, I consider myself lucky to have found it. This one combines these two characteristics, which is super rare. It's another Go book for me and I still had quite a lot of "a-ha!" moments while reading it, and all of that without the unnecessary fluff, just straight to the point.
+
+- Krystian (Goodreads user)
+
 > This should be the required reading for all Golang developers before they touch code in Production... It's the Golang equivalent of the legendary 'Effective Java' by Joshua Bloch.
 
 – _Neeraj Shah_
@@ -20,15 +24,13 @@ If you're a Go developer looking to improve your skills, this book is for you. W
 
 ### Where to Buy?
 
-_100 Go Mistakes and How to Avoid Them_ (🇬🇧 edition: paper, digital, or audiobook):
+* _100 Go Mistakes and How to Avoid Them_ (🇬🇧 edition: paper, digital, or audiobook)
+	* [Manning](https://www.manning.com/books/100-go-mistakes-and-how-to-avoid-them)
+	* [O’Reilly](https://www.oreilly.com/library/view/100-go-mistakes/9781617299599/)
+	* Amazon: [.com](https://www.amazon.com/dp/1617299596), [.co.uk](https://www.amazon.co.uk/dp/B0BBSNJR6B), [.de](https://www.amazon.de/dp/B0BBHQD8BQ), [.fr](https://www.amazon.fr/100-Mistakes-How-Avoid-Them/dp/1617299596), [.in](https://www.amazon.in/dp/B0BBHQD8BQ), [.co.jp](https://www.amazon.co.jp/dp/B0BBHQD8BQ), [.es](https://www.amazon.es/dp/B0BBHQD8BQ), [.it](https://www.amazon.it/dp/B0BBHQD8BQ), [.com.br](https://www.amazon.com.br/dp/B0BBHQD8BQ)
 
-  * [Manning](https://www.manning.com/books/100-go-mistakes-and-how-to-avoid-them)
-  * [O’Reilly](https://www.oreilly.com/library/view/100-go-mistakes/9781617299599/)
-  * Amazon: [.com](https://www.amazon.com/dp/1617299596), [.co.uk](https://www.amazon.co.uk/dp/B0BBSNJR6B), [.de](https://www.amazon.de/dp/B0BBHQD8BQ), [.fr](https://www.amazon.fr/100-Mistakes-How-Avoid-Them/dp/1617299596), [.in](https://www.amazon.in/dp/B0BBHQD8BQ), [.co.jp](https://www.amazon.co.jp/dp/B0BBHQD8BQ), [.es](https://www.amazon.es/dp/B0BBHQD8BQ), [.it](https://www.amazon.it/dp/B0BBHQD8BQ), [.com.br](https://www.amazon.com.br/dp/B0BBHQD8BQ)
-
-_Go言語100Tips 開発者にありがちな間違いへの対処法_ (🇯🇵 edition):
-
-  * Amazon: [.co.jp](https://www.amazon.co.jp/exec/obidos/ASIN/4295017531/)
+* _Go言語100Tips 開発者にありがちな間違いへの対処法_ (🇯🇵 edition)
+	* Amazon: [.co.jp](https://www.amazon.co.jp/exec/obidos/ASIN/4295017531/)
 
 ## About the Author
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 148d15a..3405370 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,5 @@
 site_name: 100 Go Mistakes
+site_url: https://100go.co
 theme:
   name: material
   custom_dir: overrides
@@ -11,7 +12,7 @@ theme:
       toggle:
         icon: material/brightness-7 
         name: Switch to dark mode
-      primary: green
+      primary: cyan
     # Palette toggle for dark mode
     - scheme: slate
       toggle:
@@ -21,6 +22,7 @@ theme:
 repo_url: https://github.com/teivah/100-go-mistakes
 plugins:
   - search
+  - social
 extra:
   alternate:
     - name: English
diff --git a/site/404.html b/site/404.html
index 37a9737..5462f7e 100644
--- a/site/404.html
+++ b/site/404.html
@@ -57,7 +57,7 @@
     
     
     
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo">
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo">
   
     
     
@@ -112,7 +112,7 @@
     
     
     
-    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
     
       <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69Z"/></svg>
@@ -354,11 +354,11 @@
   
   
     <li class="md-nav__item">
-      <a href="/chinese/presentation/" class="md-nav__link">
+      <a href="/chinese/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Presentation
+    Index
   </span>
   
 
diff --git a/site/assets/images/social/chinese/index.png b/site/assets/images/social/chinese/index.png
new file mode 100644
index 0000000..1e105c7
Binary files /dev/null and b/site/assets/images/social/chinese/index.png differ
diff --git a/site/assets/images/social/index.png b/site/assets/images/social/index.png
new file mode 100644
index 0000000..ca6e538
Binary files /dev/null and b/site/assets/images/social/index.png differ
diff --git a/site/assets/images/social/jobs.png b/site/assets/images/social/jobs.png
new file mode 100644
index 0000000..b00f0a3
Binary files /dev/null and b/site/assets/images/social/jobs.png differ
diff --git a/site/assets/images/social/mistakes.png b/site/assets/images/social/mistakes.png
new file mode 100644
index 0000000..e039f27
Binary files /dev/null and b/site/assets/images/social/mistakes.png differ
diff --git a/site/chinese/presentation/index.html b/site/chinese/index.html
similarity index 82%
rename from site/chinese/presentation/index.html
rename to site/chinese/index.html
index 4540434..f55592b 100644
--- a/site/chinese/presentation/index.html
+++ b/site/chinese/index.html
@@ -8,22 +8,24 @@
       
       
       
+        <link rel="canonical" href="https://100go.co/chinese/">
       
-        <link rel="prev" href="../../mistakes/">
+      
+        <link rel="prev" href="../mistakes/">
       
       
       
-      <link rel="icon" href="../../Go-Logo_Fuchsia.svg">
+      <link rel="icon" href="../Go-Logo_Fuchsia.svg">
       <meta name="generator" content="mkdocs-1.5.2, mkdocs-material-9.3.1">
     
     
   <title>100 Go Mistakes</title>
 
     
-      <link rel="stylesheet" href="../../assets/stylesheets/main.046329b4.min.css">
+      <link rel="stylesheet" href="../assets/stylesheets/main.046329b4.min.css">
       
         
-        <link rel="stylesheet" href="../../assets/stylesheets/palette.85d0ee34.min.css">
+        <link rel="stylesheet" href="../assets/stylesheets/palette.85d0ee34.min.css">
       
       
 
@@ -42,12 +44,38 @@
       
     
     
-    <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
+    <script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
     
       
 
     
     
+      
+        <meta  property="og:type"  content="website" >
+      
+        <meta  property="og:title"  content="Index - 100 Go Mistakes" >
+      
+        <meta  property="og:description"  content="None" >
+      
+        <meta  property="og:image"  content="https://100go.co/assets/images/social/chinese/index.png" >
+      
+        <meta  property="og:image:type"  content="image/png" >
+      
+        <meta  property="og:image:width"  content="1200" >
+      
+        <meta  property="og:image:height"  content="630" >
+      
+        <meta  property="og:url"  content="https://100go.co/chinese/" >
+      
+        <meta  name="twitter:card"  content="summary_large_image" >
+      
+        <meta  name="twitter:title"  content="Index - 100 Go Mistakes" >
+      
+        <meta  name="twitter:description"  content="None" >
+      
+        <meta  name="twitter:image"  content="https://100go.co/assets/images/social/chinese/index.png" >
+      
+    
     
   </head>
   
@@ -59,7 +87,7 @@
     
     
     
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo">
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo">
   
     
     
@@ -82,9 +110,9 @@
 
 <header class="md-header md-header--shadow" data-md-component="header">
   <nav class="md-header__inner md-grid" aria-label="Header">
-    <a href="../.." title="100 Go Mistakes" class="md-header__button md-logo" aria-label="100 Go Mistakes" data-md-component="logo">
+    <a href=".." title="100 Go Mistakes" class="md-header__button md-logo" aria-label="100 Go Mistakes" data-md-component="logo">
       
-  <img src="../../Go-Logo_Fuchsia.svg" alt="logo">
+  <img src="../Go-Logo_Fuchsia.svg" alt="logo">
 
     </a>
     <label class="md-header__button md-icon" for="__drawer">
@@ -101,7 +129,7 @@
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             
-              Presentation
+              Index
             
           </span>
         </div>
@@ -114,7 +142,7 @@
     
     
     
-    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
     
       <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69Z"/></svg>
@@ -237,9 +265,9 @@
 
 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
   <label class="md-nav__title" for="__drawer">
-    <a href="../.." title="100 Go Mistakes" class="md-nav__button md-logo" aria-label="100 Go Mistakes" data-md-component="logo">
+    <a href=".." title="100 Go Mistakes" class="md-nav__button md-logo" aria-label="100 Go Mistakes" data-md-component="logo">
       
-  <img src="../../Go-Logo_Fuchsia.svg" alt="logo">
+  <img src="../Go-Logo_Fuchsia.svg" alt="logo">
 
     </a>
     100 Go Mistakes
@@ -265,7 +293,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../.." class="md-nav__link">
+      <a href=".." class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -284,7 +312,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../jobs/" class="md-nav__link">
+      <a href="../jobs/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -303,7 +331,7 @@
   
   
     <li class="md-nav__item">
-      <a href="../../mistakes/" class="md-nav__link">
+      <a href="../mistakes/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
@@ -369,7 +397,7 @@
         
   
   <span class="md-ellipsis">
-    Presentation
+    Index
   </span>
   
 
@@ -421,7 +449,7 @@
   
 
 
-  <h1>Presentation</h1>
+  <h1>Index</h1>
 
 <p>TODO</p>
 
@@ -471,10 +499,10 @@
       <div class="md-dialog__inner md-typeset"></div>
     </div>
     
-    <script id="__config" type="application/json">{"base": "../..", "features": [], "search": "../../assets/javascripts/workers/search.dfff1995.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
+    <script id="__config" type="application/json">{"base": "..", "features": [], "search": "../assets/javascripts/workers/search.dfff1995.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
     
     
-      <script src="../../assets/javascripts/bundle.dff1b7c8.min.js"></script>
+      <script src="../assets/javascripts/bundle.dff1b7c8.min.js"></script>
       
     
   </body>
diff --git a/site/index.html b/site/index.html
index 1df8a6c..899c42c 100644
--- a/site/index.html
+++ b/site/index.html
@@ -8,6 +8,8 @@
       
       
       
+        <link rel="canonical" href="https://100go.co/">
+      
       
       
         <link rel="next" href="jobs/">
@@ -48,6 +50,32 @@
 
     
     
+      
+        <meta  property="og:type"  content="website" >
+      
+        <meta  property="og:title"  content="📖 Book Presentation" >
+      
+        <meta  property="og:description"  content="None" >
+      
+        <meta  property="og:image"  content="https://100go.co/assets/images/social/index.png" >
+      
+        <meta  property="og:image:type"  content="image/png" >
+      
+        <meta  property="og:image:width"  content="1200" >
+      
+        <meta  property="og:image:height"  content="630" >
+      
+        <meta  property="og:url"  content="https://100go.co/" >
+      
+        <meta  name="twitter:card"  content="summary_large_image" >
+      
+        <meta  name="twitter:title"  content="📖 Book Presentation" >
+      
+        <meta  name="twitter:description"  content="None" >
+      
+        <meta  name="twitter:image"  content="https://100go.co/assets/images/social/index.png" >
+      
+    
     
   </head>
   
@@ -59,7 +87,7 @@
     
     
     
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo">
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo">
   
     
     
@@ -119,7 +147,7 @@
     
     
     
-    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
     
       <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69Z"/></svg>
@@ -476,11 +504,11 @@
   
   
     <li class="md-nav__item">
-      <a href="chinese/presentation/" class="md-nav__link">
+      <a href="chinese/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Presentation
+    Index
   </span>
   
 
@@ -617,12 +645,18 @@
 
 
 <h1 id="book-presentation">📖 Book Presentation</h1>
-<p>Source code and community space of 📖 <em>100 Go Mistakes and How to Avoid Them</em>, published by Manning in August 2022.</p>
+<p>Source code and community space of <em>100 Go Mistakes and How to Avoid Them</em>, published by Manning in 2022.</p>
+<p><img alt="" src="cover.png" /></p>
 <h2 id="book-description">Book Description</h2>
 <p>If you're a Go developer looking to improve your skills, this book is for you. With a focus on practical examples, <em>100 Go Mistakes and How to Avoid Them</em> covers a wide range of topics from concurrency and error handling to testing and code organization. You'll learn to write more idiomatic, efficient, and maintainable code and become a proficient Go developer.</p>
-<p><img alt="" src="cover.png" /></p>
 <h3 id="quotes">Quotes</h3>
 <blockquote>
+<p>This is an exceptional book. Usually, if a book contains either high-quality explanations or is written succinctly, I consider myself lucky to have found it. This one combines these two characteristics, which is super rare. It's another Go book for me and I still had quite a lot of "a-ha!" moments while reading it, and all of that without the unnecessary fluff, just straight to the point.</p>
+</blockquote>
+<ul>
+<li>Krystian (Goodreads user)</li>
+</ul>
+<blockquote>
 <p>This should be the required reading for all Golang developers before they touch code in Production... It's the Golang equivalent of the legendary 'Effective Java' by Joshua Bloch.</p>
 </blockquote>
 <p>– <em>Neeraj Shah</em></p>
@@ -631,16 +665,22 @@
 </blockquote>
 <p>– <em>Anupam Sengupta</em></p>
 <h3 id="where-to-buy">Where to Buy?</h3>
-<p><em>100 Go Mistakes and How to Avoid Them</em> (🇬🇧 edition: paper, digital, or audiobook):</p>
+<ul>
+<li>
+<p><em>100 Go Mistakes and How to Avoid Them</em> (🇬🇧 edition: paper, digital, or audiobook)</p>
 <ul>
 <li><a href="https://www.manning.com/books/100-go-mistakes-and-how-to-avoid-them">Manning</a></li>
 <li><a href="https://www.oreilly.com/library/view/100-go-mistakes/9781617299599/">O’Reilly</a></li>
 <li>Amazon: <a href="https://www.amazon.com/dp/1617299596">.com</a>, <a href="https://www.amazon.co.uk/dp/B0BBSNJR6B">.co.uk</a>, <a href="https://www.amazon.de/dp/B0BBHQD8BQ">.de</a>, <a href="https://www.amazon.fr/100-Mistakes-How-Avoid-Them/dp/1617299596">.fr</a>, <a href="https://www.amazon.in/dp/B0BBHQD8BQ">.in</a>, <a href="https://www.amazon.co.jp/dp/B0BBHQD8BQ">.co.jp</a>, <a href="https://www.amazon.es/dp/B0BBHQD8BQ">.es</a>, <a href="https://www.amazon.it/dp/B0BBHQD8BQ">.it</a>, <a href="https://www.amazon.com.br/dp/B0BBHQD8BQ">.com.br</a></li>
 </ul>
-<p><em>Go言語100Tips 開発者にありがちな間違いへの対処法</em> (🇯🇵 edition):</p>
+</li>
+<li>
+<p><em>Go言語100Tips 開発者にありがちな間違いへの対処法</em> (🇯🇵 edition)</p>
 <ul>
 <li>Amazon: <a href="https://www.amazon.co.jp/exec/obidos/ASIN/4295017531/">.co.jp</a></li>
 </ul>
+</li>
+</ul>
 <h2 id="about-the-author">About the Author</h2>
 <p>Teiva Harsanyi is a senior software engineer at Google. He has worked in various domains, including insurance, transportation, and safety-critical industries like air traffic management. He is passionate about Go and how to design and implement reliable systems.</p>
 <h2 id="external-resources">External Resources</h2>
diff --git a/site/jobs/index.html b/site/jobs/index.html
index ccd8f9d..38a6dd8 100644
--- a/site/jobs/index.html
+++ b/site/jobs/index.html
@@ -8,6 +8,8 @@
       
       
       
+        <link rel="canonical" href="https://100go.co/jobs/">
+      
       
         <link rel="prev" href="..">
       
@@ -50,6 +52,32 @@
 
     
     
+      
+        <meta  property="og:type"  content="website" >
+      
+        <meta  property="og:title"  content="❤️ Go Jobs - 100 Go Mistakes" >
+      
+        <meta  property="og:description"  content="None" >
+      
+        <meta  property="og:image"  content="https://100go.co/assets/images/social/jobs.png" >
+      
+        <meta  property="og:image:type"  content="image/png" >
+      
+        <meta  property="og:image:width"  content="1200" >
+      
+        <meta  property="og:image:height"  content="630" >
+      
+        <meta  property="og:url"  content="https://100go.co/jobs/" >
+      
+        <meta  name="twitter:card"  content="summary_large_image" >
+      
+        <meta  name="twitter:title"  content="❤️ Go Jobs - 100 Go Mistakes" >
+      
+        <meta  name="twitter:description"  content="None" >
+      
+        <meta  name="twitter:image"  content="https://100go.co/assets/images/social/jobs.png" >
+      
+    
     
   </head>
   
@@ -61,7 +89,7 @@
     
     
     
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo">
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo">
   
     
     
@@ -121,7 +149,7 @@
     
     
     
-    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
     
       <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69Z"/></svg>
@@ -373,11 +401,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../chinese/presentation/" class="md-nav__link">
+      <a href="../chinese/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Presentation
+    Index
   </span>
   
 
diff --git a/site/mistakes/index.html b/site/mistakes/index.html
index 78ef82f..ac65b12 100644
--- a/site/mistakes/index.html
+++ b/site/mistakes/index.html
@@ -8,11 +8,13 @@
       
       
       
+        <link rel="canonical" href="https://100go.co/mistakes/">
+      
       
         <link rel="prev" href="../jobs/">
       
       
-        <link rel="next" href="../chinese/presentation/">
+        <link rel="next" href="../chinese/">
       
       
       <link rel="icon" href="../Go-Logo_Fuchsia.svg">
@@ -50,6 +52,32 @@
 
     
     
+      
+        <meta  property="og:type"  content="website" >
+      
+        <meta  property="og:title"  content="💡 Go Mistakes - 100 Go Mistakes" >
+      
+        <meta  property="og:description"  content="None" >
+      
+        <meta  property="og:image"  content="https://100go.co/assets/images/social/mistakes.png" >
+      
+        <meta  property="og:image:type"  content="image/png" >
+      
+        <meta  property="og:image:width"  content="1200" >
+      
+        <meta  property="og:image:height"  content="630" >
+      
+        <meta  property="og:url"  content="https://100go.co/mistakes/" >
+      
+        <meta  name="twitter:card"  content="summary_large_image" >
+      
+        <meta  name="twitter:title"  content="💡 Go Mistakes - 100 Go Mistakes" >
+      
+        <meta  name="twitter:description"  content="None" >
+      
+        <meta  name="twitter:image"  content="https://100go.co/assets/images/social/mistakes.png" >
+      
+    
     
   </head>
   
@@ -61,7 +89,7 @@
     
     
     
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo">
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo">
   
     
     
@@ -121,7 +149,7 @@
     
     
     
-    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="green" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="cyan" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
     
       <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12 20 8.69Z"/></svg>
@@ -1273,11 +1301,11 @@
   
   
     <li class="md-nav__item">
-      <a href="../chinese/presentation/" class="md-nav__link">
+      <a href="../chinese/" class="md-nav__link">
         
   
   <span class="md-ellipsis">
-    Presentation
+    Index
   </span>
   
 
diff --git a/site/search/search_index.json b/site/search/search_index.json
index ca2d23b..8fe2e79 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udcd6 Book Presentation","text":"<p>Source code and community space of \ud83d\udcd6 100 Go Mistakes and How to Avoid Them, published by Manning in August 2022.</p>"},{"location":"#book-description","title":"Book Description","text":"<p>If you're a Go developer looking to improve your skills, this book is for you. With a focus on practical examples, 100 Go Mistakes and How to Avoid Them covers a wide range of topics from concurrency and error handling to testing and code organization. You'll learn to write more idiomatic, efficient, and maintainable code and become a proficient Go developer.</p> <p></p>"},{"location":"#quotes","title":"Quotes","text":"<p>This should be the required reading for all Golang developers before they touch code in Production... It's the Golang equivalent of the legendary 'Effective Java' by Joshua Bloch.</p> <p>\u2013 Neeraj Shah</p> <p>Not having this will be the 101st mistake a Go programmer could make.</p> <p>\u2013 Anupam Sengupta</p>"},{"location":"#where-to-buy","title":"Where to Buy?","text":"<p>100 Go Mistakes and How to Avoid Them (\ud83c\uddec\ud83c\udde7 edition: paper, digital, or audiobook):</p> <ul> <li>Manning</li> <li>O\u2019Reilly</li> <li>Amazon: .com, .co.uk, .de, .fr, .in, .co.jp, .es, .it, .com.br</li> </ul> <p>Go\u8a00\u8a9e100Tips \u958b\u767a\u8005\u306b\u3042\u308a\u304c\u3061\u306a\u9593\u9055\u3044\u3078\u306e\u5bfe\u51e6\u6cd5 (\ud83c\uddef\ud83c\uddf5 edition):</p> <ul> <li>Amazon: .co.jp</li> </ul>"},{"location":"#about-the-author","title":"About the Author","text":"<p>Teiva Harsanyi is a senior software engineer at Google. He has worked in various domains, including insurance, transportation, and safety-critical industries like air traffic management. He is passionate about Go and how to design and implement reliable systems.</p>"},{"location":"#external-resources","title":"External Resources","text":""},{"location":"#english","title":"English","text":"<ul> <li>Book Review: 100 Go Mistakes and How to Avoid Them: Post, YouTube</li> <li>How to make mistakes in Go - Go Time #190: Episode, Spotify</li> <li>8LU - 100% Test Coverage</li> <li>Some Tips I learned from 100 Mistakes in Go</li> <li>What can be summarized from 100 Go Mistakes?</li> </ul>"},{"location":"#chinese","title":"Chinese","text":"<ul> <li>\u6df1\u5ea6\u9605\u8bfb\u4e4b\u300a100 Go Mistakes and How to Avoid Them</li> <li>100 Go Mistakes \u968f\u8bb0</li> <li>\u6211\u4e3a\u4ec0\u4e48\u653e\u5f03Go\u8bed\u8a00\uff1f</li> </ul>"},{"location":"#japanese","title":"Japanese","text":"<ul> <li>\u6700\u8fd1\u8aad\u3093\u3060Go\u8a00\u8a9e\u306e\u672c\u306e\u7d39\u4ecb\uff1a100 Go Mistakes and How to Avoid Them</li> <li>\u300e100 Go Mistakes and How to Avoid Them\u300f\u3092\u8aad\u3080</li> <li>100 Go Mistakes \u968f\u8bb0 - 01 Code and project organization</li> </ul>"},{"location":"#portuguese","title":"Portuguese","text":"<ul> <li>Um \u00d3TIMO livro para programadores Go</li> </ul>"},{"location":"jobs/","title":"\u2764\ufe0f Go Jobs","text":"<p>Is your company hiring? Sponsor this repository and let Go developers know your opportunities in this section (traffic: +400 unique visitor per week).</p> <p>For example:</p>"},{"location":"jobs/#company-remote-usa-96000-to-120000-a-year","title":"[Company] Remote (USA) - $96,000 to $120,000 a year","text":""},{"location":"jobs/#job-description","title":"Job Description","text":"<p>...</p>"},{"location":"jobs/#qualifications","title":"Qualifications","text":"<p>...</p>"},{"location":"mistakes/","title":"\ud83d\udca1 Go Mistakes","text":"<p>This section contains a summary of the 100 mistakes in the book. Meanwhile, it's also a section open to the community. If you believe that a mistake should be added, please create a community mistake issue.</p> <p>Note: You're currently viewing a new version that I'm enriching with significantly more content. Yet, this version is still under development; please be gentle if you find an issue, and feel free to create a PR.</p> <p></p>"},{"location":"mistakes/#code-and-project-organization","title":"Code and Project Organization","text":""},{"location":"mistakes/#unintended-variable-shadowing-1","title":"Unintended variable shadowing (#1)","text":"<p>TL;DR: Avoiding shadowed variables can help prevent mistakes like referencing the wrong variable or confusing readers.</p> <p>Variable shadowing occurs when a variable name is redeclared in an inner block, but this practice is prone to mistakes. Imposing a rule to forbid shadowed variables depends on personal taste. For example, sometimes it can be convenient to reuse an existing variable name like <code>err</code> for errors. Yet, in general, we should remain cautious because we now know that we can face a scenario where the code compiles, but the variable that receives the value is not the one expected.</p> <p>Source code</p>"},{"location":"mistakes/#unnecessary-nested-code-2","title":"Unnecessary nested code (#2)","text":"<p>TL;DR: Avoiding nested levels and keeping the happy path aligned on the left makes building a mental code model easier.</p> <p>In general, the more nested levels a function requires, the more complex it is to read and understand. Let\u2019s see some different applications of this rule to optimize our code for readability:</p> <ul> <li>When an <code>if</code> block returns, we should omit the <code>else</code> block in all cases. For example, we shouldn\u2019t write:</li> </ul> <p><code>go   if foo() {       // ...       return true   } else {       // ...   }</code></p> <p>Instead, we omit the <code>else</code> block like this:</p> <p><code>go   if foo() {       // ...       return true   }   // ...</code> * We can also follow this logic with a non-happy path:</p> <p><code>go   if s != \"\" {       // ...   } else {       return errors.New(\"empty string\")   }</code></p> <p>Here, an empty <code>s</code> represents the non-happy path. Hence, we should flip the   condition like so:</p> <p><code>go   if s == \"\" {       return errors.New(\"empty string\")   }   // ...</code></p> <p>Writing readable code is an important challenge for every developer. Striving to reduce the number of nested blocks, aligning the happy path on the left, and returning as early as possible are concrete means to improve our code\u2019s readability.</p> <p>Source code</p>"},{"location":"mistakes/#misusing-init-functions-3","title":"Misusing init functions (#3)","text":"<p>TL;DR: When initializing variables, remember that init functions have limited error handling and make state handling and testing more complex. In most cases, initializations should be handled as specific functions.</p> <p>An init function is a function used to initialize the state of an application. It takes no arguments and returns no result (a <code>func()</code> function). When a package is initialized, all the constant and variable declarations in the package are evaluated. Then, the init functions are executed.</p> <p>Init functions can lead to some issues: * They can limit error management. * They can complicate how to implement tests (for example, an external dependency must be set up, which may not be necessary for the scope of unit tests). * If the initialization requires us to set a state, that has to be done through global variables.</p> <p>We should be cautious with init functions. They can be helpful in some situations, however, such as defining static configuration. Otherwise, and in most cases, we should handle initializations through ad hoc functions.</p> <p>Source code</p>"},{"location":"mistakes/#overusing-getters-and-setters-4","title":"Overusing getters and setters (#4)","text":"<p>TL;DR: Forcing the use of getters and setters isn\u2019t idiomatic in Go. Being pragmatic and finding the right balance between efficiency and blindly following certain idioms should be the way to go.</p> <p>Data encapsulation refers to hiding the values or state of an object. Getters and setters are means to enable encapsulation by providing exported methods on top of unexported object fields.</p> <p>In Go, there is no automatic support for getters and setters as we see in some languages. It is also considered neither mandatory nor idiomatic to use getters and setters to access struct fields. We shouldn\u2019t overwhelm our code with getters and setters on structs if they don\u2019t bring any value. We should be pragmatic and strive to find the right balance between efficiency and following idioms that are sometimes considered indisputable in other programming paradigms.</p> <p>Remember that Go is a unique language designed for many characteristics, including simplicity. However, if we find a need for getters and setters or, as mentioned, foresee a future need while guaranteeing forward compatibility, there\u2019s nothing wrong with using them.</p>"},{"location":"mistakes/#interface-pollution-5","title":"Interface pollution (#5)","text":"<p>TL;DR: Abstractions should be discovered, not created. To prevent unnecessary complexity, create an interface when you need it and not when you foresee needing it, or if you can at least prove the abstraction to be a valid one.</p> <p>An interface provides a way to specify the behavior of an object. We use interfaces to create common abstractions that multiple objects can implement. What makes Go interfaces so different is that they are satisfied implicitly. There is no explicit keyword like <code>implements</code> to mark that an object <code>X</code> implements interface <code>Y</code>.</p> <p>In general, we can define three main use cases where interfaces are generally considered as bringing value: factoring out a common behavior, creating some decoupling, and restricting a type to a certain behavior. Yet, this list isn't exhaustive and will also depend on the context we face.</p> <p>In many occasions, interfaces are made to create abstractions. And the main caveat when programming meets abstractions is remembering that abstractions should be discovered, not created. What does this mean? It means we shouldn\u2019t start creating abstractions in our code if there is no immediate reason to do so. We shouldn\u2019t design with interfaces but wait for a concrete need. Said differently, we should create an interface when we need it, not when we foresee that we could need it. What\u2019s the main problem if we overuse interfaces? The answer is that they make the code flow more complex. Adding a useless level of indirection doesn\u2019t bring any value; it creates a worthless abstraction making the code more difficult to read, understand, and reason about. If we don\u2019t have a strong reason for adding an interface and it\u2019s unclear how an interface makes a code better, we should challenge this interface\u2019s purpose. Why not call the implementation directly?</p> <p>We should be cautious when creating abstractions in our code (abstractions should be discovered, not created). It\u2019s common for us, software developers, to overengineer our code by trying to guess what the perfect level of abstraction is, based on what we think we might need later. This process should be avoided because, in most cases, it pollutes our code with unnecessary abstractions, making it more complex to read.</p> <p>Don\u2019t design with interfaces, discover them.</p> <p>\u2013  Rob Pike</p> <p>Let\u2019s not try to solve a problem abstractly but solve what has to be solved now. Last, but not least, if it\u2019s unclear how an interface makes the code better, we should probably consider removing it to make our code simpler.</p> <p>Source code</p>"},{"location":"mistakes/#interface-on-the-producer-side-6","title":"Interface on the producer side (#6)","text":"<p>TL;DR: Keeping interfaces on the client side avoids unnecessary abstractions.</p> <p>Interfaces are satisfied implicitly in Go, which tends to be a gamechanger compared to languages with an explicit implementation. In most cases, the approach to follow is similar to what we described in the previous section: abstractions should be discovered, not created. This means that it\u2019s not up to the producer to force a given abstraction for all the clients. Instead, it\u2019s up to the client to decide whether it needs some form of abstraction and then determine the best abstraction level for its needs.</p> <p>An interface should live on the consumer side in most cases. However, in particular contexts (for example, when we know\u2014not foresee\u2014that an abstraction will be helpful for consumers), we may want to have it on the producer side. If we do, we should strive to keep it as minimal as possible, increasing its reusability potential and making it more easily composable.</p> <p>Source code</p>"},{"location":"mistakes/#returning-interfaces-7","title":"Returning interfaces (#7)","text":"<p>TL;DR: To prevent being restricted in terms of flexibility, a function shouldn\u2019t return interfaces but concrete implementations in most cases. Conversely, a function should accept interfaces whenever possible.</p> <p>In most cases, we shouldn\u2019t return interfaces but concrete implementations. Otherwise, it can make our design more complex due to package dependencies and can restrict flexibility because all the clients would have to rely on the same abstraction. Again, the conclusion is similar to the previous sections: if we know (not foresee) that an abstraction will be helpful for clients, we can consider returning an interface. Otherwise, we shouldn\u2019t force abstractions; they should be discovered by clients. If a client needs to abstract an implementation for whatever reason, it can still do that on the client\u2019s side.</p>"},{"location":"mistakes/#any-says-nothing-8","title":"<code>any</code> says nothing (#8)","text":"<p>TL;DR: Only use <code>any</code> if you need to accept or return any possible type, such as <code>json.Marshal</code>. Otherwise, <code>any</code> doesn\u2019t provide meaningful information and can lead to compile-time issues by allowing a caller to call methods with any data type.</p> <p>The <code>any</code> type can be helpful if there is a genuine need for accepting or returning any possible type (for instance, when it comes to marshaling or formatting). In general, we should avoid overgeneralizing the code we write at all costs. Perhaps a little bit of duplicated code might occasionally be better if it improves other aspects such as code expressiveness.</p> <p>Source code</p>"},{"location":"mistakes/#being-confused-about-when-to-use-generics-9","title":"Being confused about when to use generics (#9)","text":"<p>TL;DR: Relying on generics and type parameters can prevent writing boilerplate code to factor out elements or behaviors. However, do not use type parameters prematurely, but only when you see a concrete need for them. Otherwise, they introduce unnecessary abstractions and complexity.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-aware-of-the-possible-problems-with-type-embedding-10","title":"Not being aware of the possible problems with type embedding (#10)","text":"<p>TL;DR: Using type embedding can also help avoid boilerplate code; however, ensure that doing so doesn\u2019t lead to visibility issues where some fields should have remained hidden.</p> <p>When creating a struct, Go offers the option to embed types. But this can sometimes lead to unexpected behaviors if we don\u2019t understand all the implications of type embedding. Throughout this section, we look at how to embed types, what these bring, and the possible issues.</p> <p>In Go, a struct field is called embedded if it\u2019s declared without a name. For example,</p> <pre><code>type Foo struct {\n    Bar // Embedded field\n}\n\ntype Bar struct {\n    Baz int\n}\n</code></pre> <p>In the <code>Foo</code> struct, the <code>Bar</code> type is declared without an associated name; hence, it\u2019s an embedded field.</p> <p>We use embedding to promote the fields and methods of an embedded type. Because Bar contains a Baz field, this field is promoted to <code>Foo</code>. Therefore, Baz becomes available from Foo.</p> <p>What can we say about type embedding? First, let\u2019s note that it\u2019s rarely a necessity, and it means that whatever the use case, we can probably solve it as well without type embedding. Type embedding is mainly used for convenience: in most cases, to promote behaviors.</p> <p>If we decide to use type embedding, we need to keep two main constraints in mind: * It shouldn\u2019t be used solely as some syntactic sugar to simplify accessing a field (such as <code>Foo.Baz()</code> instead of <code>Foo.Bar.Baz()</code>). If this is the only rationale, let\u2019s not embed the inner type and use a field instead. * It shouldn\u2019t promote data (fields) or a behavior (methods) we want to hide from the outside: for example, if it allows clients to access a locking behavior that should remain private to the struct.</p> <p>Using type embedding consciously by keeping these constraints in mind can help avoid boilerplate code with additional forwarding methods. However, let\u2019s make sure we don\u2019t do it solely for cosmetics and not promote elements that should remain hidden.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-the-functional-options-pattern-11","title":"Not using the functional options pattern (#11)","text":"<p>TL;DR: To handle options conveniently and in an API-friendly manner, use the functional options pattern.</p> <p>Although there are different implementations with minor variations, the main idea is as follows: * An unexported struct holds the configuration: options. * Each option is a function that returns the same type: <code>type Option func(options *options)</code> error. For example, <code>WithPort</code> accepts an <code>int</code> argument that represents the port and returns an <code>Option</code> type that represents how to update the <code>options</code> struct.</p> <p></p> <pre><code>type options struct {\n  port *int\n}\n\ntype Option func(options *options) error\n\nfunc WithPort(port int) Option {\n  return func(options *options) error {\n    if port &lt; 0 {\n    return errors.New(\"port should be positive\")\n  }\n  options.port = &amp;port\n  return nil\n  }\n}\n\nfunc NewServer(addr string, opts ...Option) ( *http.Server, error) { &lt;1&gt;\n  var options options &lt;2&gt;\n  for _, opt := range opts { &lt;3&gt;\n    err := opt(&amp;options) &lt;4&gt;\n    if err != nil {\n      return nil, err\n    }\n  }\n\n  // At this stage, the options struct is built and contains the config\n  // Therefore, we can implement our logic related to port configuration\n  var port int\n  if options.port == nil {\n    port = defaultHTTPPort\n  } else {\n      if *options.port == 0 {\n      port = randomPort()\n    } else {\n      port = *options.port\n    }\n  }\n\n  // ...\n}\n</code></pre> <p>The functional options pattern provides a handy and API-friendly way to handle options. Although the builder pattern can be a valid option, it has some minor downsides (having to pass a config struct that can be empty or a less handy way to handle error management) that tend to make the functional options pattern the idiomatic way to deal with these kind of problems in Go.</p> <p>Source code</p>"},{"location":"mistakes/#project-misorganization-project-structure-and-package-organization-12","title":"Project misorganization (project structure and package organization) (#12)","text":"<p>TL;DR: Following a layout such as project-layout can be a good way to start structuring Go projects, especially if you are looking for existing conventions to standardize a new project.</p> <p>Regarding the overall organization, there are different schools of thought. For example, should we organize our application by context or by layer? It depends on our preferences. We may favor grouping code per context (such as the customer context, the contract context, etc.), or we may favor following hexagonal architecture principles and group per technical layer. If the decision we make fits our use case, it cannot be a wrong decision, as long as we remain consistent with it.</p> <p>Regarding packages, there are multiple best practices that we should follow. First, we should avoid premature packaging because it might cause us to overcomplicate a project. Sometimes, it\u2019s better to use a simple organization and have our project evolve when we understand what it contains rather than forcing ourselves to make the perfect structure up front. Granularity is another essential thing to consider. We should avoid having dozens of nano packages containing only one or two files. If we do, it\u2019s because we have probably missed some logical connections across these packages, making our project harder for readers to understand. Conversely, we should also avoid huge packages that dilute the meaning of a package name.</p> <p>Package naming should also be considered with care. As we all know (as developers), naming is hard. To help clients understand a Go project, we should name our packages after what they provide, not what they contain. Also, naming should be meaningful. Therefore, a package name should be short, concise, expressive, and, by convention, a single lowercase word.</p> <p>Regarding what to export, the rule is pretty straightforward. We should minimize what should be exported as much as possible to reduce the coupling between packages and keep unnecessary exported elements hidden. If we are unsure whether to export an element or not, we should default to not exporting it. Later, if we discover that we need to export it, we can adjust our code. Let\u2019s also keep in mind some exceptions, such as making fields exported so that a struct can be unmarshaled with encoding/json.</p> <p>Organizing a project isn\u2019t straightforward, but following these rules should help make it easier to maintain. However, remember that consistency is also vital to ease maintainability. Therefore, let\u2019s make sure that we keep things as consistent as possible within a codebase.</p>"},{"location":"mistakes/#creating-utility-packages-13","title":"Creating utility packages (#13)","text":"<p>TL;DR: Naming is a critical piece of application design. Creating packages such as <code>common</code>, <code>util</code>, and <code>shared</code> doesn\u2019t bring much value for the reader. Refactor such packages into meaningful and specific package names.</p> <p>Also, bear in mind that naming a package after what it provides and not what it contains can be an efficient way to increase its expressiveness.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-package-name-collisions-14","title":"Ignoring package name collisions (#14)","text":"<p>TL;DR: To avoid naming collisions between variables and packages, leading to confusion or perhaps even bugs, use unique names for each one. If this isn\u2019t feasible, use an import alias to change the qualifier to differentiate the package name from the variable name, or think of a better name.</p> <p>Package collisions occur when a variable name collides with an existing package name, preventing the package from being reused. We should prevent variable name collisions to avoid ambiguity. If we face a collision, we should either find another meaningful name or use an import alias.</p>"},{"location":"mistakes/#missing-code-documentation-15","title":"Missing code documentation (#15)","text":"<p>TL;DR: To help clients and maintainers understand your code\u2019s purpose, document exported elements.</p> <p>Documentation is an important aspect of coding. It simplifies how clients can consume an API but can also help in maintaining a project. In Go, we should follow some rules to make our code idiomatic:</p> <p>First, every exported element must be documented. Whether it is a structure, an interface, a function, or something else, if it\u2019s exported, it must be documented. The convention is to add comments, starting with the name of the exported element.</p> <p>As a convention, each comment should be a complete sentence that ends with punctuation. Also bear in mind that when we document a function (or a method), we should highlight what the function intends to do, not how it does it; this belongs to the core of a function and comments, not documentation. Furthermore, the documentation should ideally provide enough information that the consumer does not have to look at our code to understand how to use an exported element.</p> <p>When it comes to documenting a variable or a constant, we might be interested in conveying two aspects: its purpose and its content. The former should live as code documentation to be useful for external clients. The latter, though, shouldn\u2019t necessarily be public.</p> <p>To help clients and maintainers understand a package\u2019s scope, we should also document each package. The convention is to start the comment with <code>// Package</code> followed by the package name. The first line of a package comment should be concise. That\u2019s because it will appear in the package. Then, we can provide all the information we need in the following lines.</p> <p>Documenting our code shouldn\u2019t be a constraint. We should take the opportunity to make sure it helps clients and maintainers to understand the purpose of our code.</p>"},{"location":"mistakes/#not-using-linters-16","title":"Not using linters (#16)","text":"<p>TL;DR: To improve code quality and consistency, use linters and formatters.</p> <p>A linter is an automatic tool to analyze code and catch errors. The scope of this section isn\u2019t to give an exhaustive list of the existing linters; otherwise, it will become deprecated pretty quickly. But we should understand and remember why linters are essential for most Go projects.</p> <p>However, if you\u2019re not a regular user of linters, here is a list that you may want to use daily: * https://golang.org/cmd/vet/\u2014A standard Go analyzer * https://github.com/kisielk/errcheck\u2014An error checker * https://github.com/fzipp/gocyclo\u2014A cyclomatic complexity analyzer * https://github.com/jgautheron/goconst\u2014A repeated string constants analyzer * Besides linters, we should also use code formatters to fix code style. Here is a list of some code formatters for you to try: * https://golang.org/cmd/gofmt/\u2014A standard Go code formatter * https://godoc.org/golang.org/x/tools/cmd/goimports\u2014A standard Go imports formatter * Meanwhile, we should also look at golangci-lint (https://github.com/golangci/ golangci-lint). It\u2019s a linting tool that provides a facade on top of many useful linters and formatters. Also, it allows running the linters in parallel to improve analysis speed, which is quite handy.</p> <p>Linters and formatters are a powerful way to improve the quality and consistency of our codebase. Let\u2019s take the time to understand which one we should use and make sure we automate their execution (such as a CI or Git precommit hook).</p>"},{"location":"mistakes/#data-types","title":"Data Types","text":""},{"location":"mistakes/#creating-confusion-with-octal-literals-17","title":"Creating confusion with octal literals (#17)","text":"<p>TL;DR: When reading existing code, bear in mind that integer literals starting with 0 are octal numbers. Also, to improve readability, make octal integers explicit by prefixing them with <code>0o</code>.</p> <p>Octal numbers start with a 0 (e.g., <code>010</code> is equal to 8 in base 10). To improve readability and avoid potential mistakes for future code readers, we should make octal numbers explicit using the <code>0o</code> prefix (e.g., <code>0o10</code>).</p> <p>We should also note the other integer literal representations: * Binary\u2014Uses a <code>0b</code> or <code>0B</code> prefix (for example, <code>0b100</code> is equal to 4 in base 10) * Hexadecimal\u2014Uses an <code>0x</code> or <code>0X</code> prefix (for example, <code>0xF</code> is equal to 15 in base 10) * Imaginary\u2014Uses an <code>i</code> suffix (for example, <code>3i</code>)</p> <p>We can also use an underscore character (_) as a separator for readability. For example, we can write 1 billion this way: <code>1_000_000_000</code>. We can also use the under- score character with other representations (for example, <code>0b00_00_01</code>).</p> <p>Source code</p>"},{"location":"mistakes/#neglecting-integer-overflows-18","title":"Neglecting integer overflows (#18)","text":"<p>TL;DR: Because integer overflows and underflows are handled silently in Go, you can implement your own functions to catch them.</p> <p>In Go, an integer overflow that can be detected at compile time generates a compila- tion error. For example,</p> <pre><code>var counter int32 = math.MaxInt32 + 1\n</code></pre> <pre><code>constant 2147483648 overflows int32\n</code></pre> <p>However, at run time, an integer overflow or underflow is silent; this does not lead to an application panic. It is essential to keep this behavior in mind, because it can lead to sneaky bugs (for example, an integer increment or addition of positive integers that leads to a negative result).</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-floating-points-19","title":"Not understanding floating-points (#19)","text":"<p>TL;DR: Making floating-point comparisons within a given delta can ensure that your code is portable. When performing addition or subtraction, group the operations with a similar order of magnitude to favor accuracy. Also, perform multiplication and division before addition and subtraction.</p> <p>In Go, there are two floating-point types (if we omit imaginary numbers): float32 and float64. The concept of a floating point was invented to solve the major problem with integers: their inability to represent fractional values. To avoid bad surprises, we need to know that floating-point arithmetic is an approximation of real arithmetic.</p> <p>For that, we\u2019ll look at a multiplication example:</p> <pre><code>var n float32 = 1.0001\nfmt.Println(n * n)\n</code></pre> <p>We may expect this code to print the result of 1.0001 * 1.0001 = 1.00020001, right? However, running it on most x86 processors prints 1.0002, instead.</p> <p>Because Go\u2019s <code>float32</code> and <code>float64</code> types are approximations, we have to bear a few rules in mind: * When comparing two floating-point numbers, check that their difference is within an acceptable range. * When performing additions or subtractions, group operations with a similar order of magnitude for better accuracy. * To favor accuracy, if a sequence of operations requires addition, subtraction, multiplication, or division, perform the multiplication and division operations first.</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-slice-length-and-capacity-20","title":"Not understanding slice length and capacity (#20)","text":"<p>TL;DR: Understanding the difference between slice length and capacity should be part of a Go developer\u2019s core knowledge. The slice length is the number of available elements in the slice, whereas the slice capacity is the number of elements in the backing array.</p> <p>Source code</p>"},{"location":"mistakes/#inefficient-slice-initialization-21","title":"Inefficient slice initialization (#21)","text":"<p>TL;DR: When creating a slice, initialize it with a given length or capacity if its length is already known. This reduces the number of allocations and improves performance.</p> <p>While initializing a slice using <code>make</code>, we can provide a length and an optional capacity. Forgetting to pass an appropriate value for both of these parameters when it makes sense is a widespread mistake. Indeed, it can lead to multiple copies and additional effort for the GC to clean the temporary backing arrays. Performance-wise, there\u2019s no good reason not to give the Go runtime a helping hand.</p> <p>Our options are to allocate a slice with either a given capacity or a given length. Of these two solutions, we have seen that the second tends to be slightly faster. But using a given capacity and append can be easier to implement and read in some contexts.</p> <p>Source code</p>"},{"location":"mistakes/#being-confused-about-nil-vs-empty-slice-22","title":"Being confused about nil vs. empty slice (#22)","text":"<p>TL;DR: To prevent common confusions such as when using the <code>encoding/json</code> or the <code>reflect</code> package, you need to understand the difference between nil and empty slices. Both are zero-length, zero-capacity slices, but only a nil slice doesn\u2019t require allocation.</p> <p>In Go, there is a distinction between nil and empty slices. A nil slice is equals to <code>nil</code>, whereas an empty slice has a length of zero. A nil slice is empty, but an empty slice isn\u2019t necessarily <code>nil</code>. Meanwhile, a nil slice doesn\u2019t require any allocation. We have seen throughout this section how to initialize a slice depending on the con- text by using</p> <ul> <li><code>var s []string</code> if we aren\u2019t sure about the final length and the slice can be empty</li> <li><code>[]string(nil)</code> as syntactic sugar to create a nil and empty slice</li> <li><code>make([]string, length)</code> if the future length is known</li> </ul> <p>The last option, <code>[]string{}</code>, should be avoided if we initialize the slice without ele- ments. Finally, let\u2019s check whether the libraries we use make the distinctions between nil and empty slices to prevent unexpected behaviors.</p> <p>Source code</p>"},{"location":"mistakes/#not-properly-checking-if-a-slice-is-empty-23","title":"Not properly checking if a slice is empty (#23)","text":"<p>TL;DR: To check if a slice doesn\u2019t contain any element, check its length. This check works regardless of whether the slice is <code>nil</code> or empty. The same goes for maps. To design unambiguous APIs, you shouldn\u2019t distinguish between nil and empty slices.</p> <p>To determine whether a slice has elements, we can either do it by checking if the slice is nil or if its length is equal to 0. Checking the length is the best option to follow as it will cover both if the slice is empty or is the slice is nil.</p> <p>Meanwhile, when designing interfaces, we should avoid distinguishing nil and empty slices, which leads to subtle programming errors. When returning slices, it should make neither a seman- tic nor a technical difference if we return a nil or empty slice. Both should mean the same thing for the callers. This principle is the same with maps. To check if a map is empty, check its length, not whether it\u2019s nil.</p> <p>Source code</p>"},{"location":"mistakes/#not-making-slice-copies-correctly-24","title":"Not making slice copies correctly (#24)","text":"<p>TL;DR: To copy one slice to another using the <code>copy</code> built-in function, remember that the number of copied elements corresponds to the minimum between the two slice\u2019s lengths.</p> <p>Copying elements from one slice to another is a reasonably frequent operation. When using copy, we must recall that the number of elements copied to the destina- tion corresponds to the minimum between the two slices\u2019 lengths. Also bear in mind that other alternatives exist to copy a slice, so we shouldn\u2019t be surprised if we find them in a codebase.</p> <p>Source code</p>"},{"location":"mistakes/#unexpected-side-effects-using-slice-append-25","title":"Unexpected side effects using slice append (#25)","text":"<p>TL;DR: Using copy or the full slice expression is a way to prevent <code>append</code> from creating conflicts if two different functions use slices backed by the same array. However, only a slice copy prevents memory leaks if you want to shrink a large slice.</p> <p>When using slicing, we must remember that we can face a situation leading to unintended side effects. If the resulting slice has a length smaller than its capacity, append can mutate the original slice. If we want to restrict the range of possible side effects, we can use either a slice copy or the full slice expression, which prevents us from doing a copy.</p> <p>[!NOTE] <code>s[low:high:max]</code> (full slice expression): This statement creates a slice similar to the one created with <code>s[low:high]</code>, except that the resulting slice\u2019s capacity is equal to <code>max - low</code>.</p> <p>Source code</p>"},{"location":"mistakes/#slice-and-memory-leaks-26","title":"Slice and memory leaks (#26)","text":"<p>TL;DR: Working with a slice of pointers or structs with pointer fields, you can avoid memory leaks by marking as nil the elements excluded by a slicing operation.</p>"},{"location":"mistakes/#leaking-capacity","title":"Leaking capacity","text":"<p>Remember that slicing a large slice or array can lead to potential high memory consumption. The remaining space won\u2019t be reclaimed by the GC, and we can keep a large backing array despite using only a few elements. Using a slice copy is the solution to prevent such a case.</p> <p>Source code</p>"},{"location":"mistakes/#slice-and-pointers","title":"Slice and pointers","text":"<p>When we use the slicing operation with pointers or structs with pointer fields, we need to know that the GC won\u2019t reclaim these elements. In that case, the two options are to either perform a copy or explicitly mark the remaining elements or their fields to <code>nil</code>.</p> <p>Source code</p>"},{"location":"mistakes/#inefficient-map-initialization-27","title":"Inefficient map initialization (#27)","text":"<p>TL;DR: When creating a map, initialize it with a given length if its length is already known. This reduces the number of allocations and improves performance.</p> <p>A map provides an unordered collection of key-value pairs in which all the keys are dis- tinct. In Go, a map is based on the hash table data structure. Internally, a hash table is an array of buckets, and each bucket is a pointer to an array of key-value pairs.</p> <p>If we know up front the number of elements a map will contain, we should create it by providing an initial size. Doing this avoids potential map growth, which is quite heavy computation-wise because it requires reallocating enough space and rebalancing all the elements.</p> <p>Source code</p>"},{"location":"mistakes/#map-and-memory-leaks-28","title":"Map and memory leaks (#28)","text":"<p>TL;DR: A map can always grow in memory, but it never shrinks. Hence, if it leads to some memory issues, you can try different options, such as forcing Go to recreate the map or using pointers.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-values-incorrectly-29","title":"Comparing values incorrectly (#29)","text":"<p>TL;DR: To compare types in Go, you can use the == and != operators if two types are comparable: Booleans, numerals, strings, pointers, channels, and structs are composed entirely of comparable types. Otherwise, you can either use <code>reflect.DeepEqual</code> and pay the price of reflection or use custom implementations and libraries.</p> <p>It\u2019s essential to understand how to use <code>==</code> and <code>!=</code> to make comparisons effectively. We can use these operators on operands that are comparable: * Booleans\u2014Compare whether two Booleans are equal. * Numerics (int, float, and complex types)\u2014Compare whether two numerics are equal. * Strings\u2014Compare whether two strings are equal. * Channels\u2014Compare whether two channels were created by the same call to make or if both are nil. * Interfaces\u2014Compare whether two interfaces have identical dynamic types and equal dynamic values or if both are nil. * Pointers\u2014Compare whether two pointers point to the same value in memory or if both are nil. * _Structs and arrays)\u2014Compare whether they are composed of similar types.</p> <p>[!NOTE] We can also use the <code>?</code>, <code>&gt;=</code>, <code>&lt;</code>, and <code>&gt;</code> operators with numeric types to compare values and with strings to compare their lexical order.</p> <p>If operands are not comparable (e.g., slices and maps), we have to use other options such as reflection. Reflection is a form of metaprogramming, and it refers to the ability of an applica- tion to introspect and modify its structure and behavior. For example, in Go, we can use <code>reflect.DeepEqual</code>. This function reports whether two elements are deeply equal by recursively traversing two values. The elements it accepts are basic types plus arrays, structs, slices, maps, pointers, interfaces, and functions. Yet, the main catch is the performance penalty.</p> <p>If performance is crucial at run time, implementing our custom method might be the best solution. One additional note: we must remember that the standard library has some exist- ing comparison methods. For example, we can use the optimized <code>bytes.Compare</code> function to compare two slices of bytes. Before implementing a custom method, we need to make sure we don\u2019t reinvent the wheel.</p> <p>Source code</p>"},{"location":"mistakes/#control-structures","title":"Control Structures","text":""},{"location":"mistakes/#ignoring-that-elements-are-copied-in-range-loops-30","title":"Ignoring that elements are copied in <code>range</code> loops (#30)","text":"<p>TL;DR: The value element in a <code>range</code> loop is a copy. Therefore, to mutate a struct, for example, access it via its index or via a classic <code>for</code> loop (unless the element or the field you want to modify is a pointer).</p> <p>A range loop allows iterating over different data structures: * String * Array * Pointer to an array * Slice * Map * Receiving channel</p> <p>Compared to a classic for <code>loop</code>, a <code>range</code> loop is a convenient way to iterate over all the elements of one of these data structures, thanks to its concise syntax.</p> <p>Yet, we should remember that the value element in a range loop is a copy. Therefore, if the value is a struct we need to mutate, we will only update the copy, not the element itself, unless the value or field we modify is a pointer. The favored options are to access the element via the index using a range loop or a classic for loop.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-arguments-are-evaluated-in-range-loops-channels-and-arrays-31","title":"Ignoring how arguments are evaluated in <code>range</code> loops (channels and arrays) (#31)","text":"<p>TL;DR: Understanding that the expression passed to the <code>range</code> operator is evaluated only once before the beginning of the loop can help you avoid common mistakes such as inefficient assignment in channel or slice iteration.</p> <p>The range loop evaluates the provided expression only once, before the beginning of the loop, by doing a copy (regardless of the type). We should remember this behavior to avoid common mistakes that might, for example, lead us to access the wrong element. For example:</p> <pre><code>a := [3]int{0, 1, 2}\nfor i, v := range a {\n    a[2] = 10\n    if i == 2 {\n        fmt.Println(v)\n    }\n}\n</code></pre> <p>This code updates the last index to 10. However, if we run this code, it does not print 10; it prints 2.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-the-impacts-of-using-pointer-elements-in-range-loops-32","title":"Ignoring the impacts of using pointer elements in <code>range</code> loops (#32)","text":"<p>TL;DR: Using a local variable or accessing an element using an index, you can prevent mistakes while copying pointers inside a loop.</p> <p>When iterating over a data structure using a <code>range</code> loop, we must recall that all the values are assigned to a unique variable with a single unique address. Therefore, if we store a pointer referencing this variable during each iteration, we will end up in a situ- ation where we store the same pointer referencing the same element: the latest one. We can overcome this issue by forcing the creation of a local variable in the loop\u2019s scope or creating a pointer referencing a slice element via its index. Both solutions are fine.</p> <p>Source code</p>"},{"location":"mistakes/#making-wrong-assumptions-during-map-iterations-ordering-and-map-insert-during-iteration-33","title":"Making wrong assumptions during map iterations (ordering and map insert during iteration) (#33)","text":"<p>TL;DR: To ensure predictable outputs when using maps, remember that a map data structure: * Doesn\u2019t order the data by keys * Doesn\u2019t preserve the insertion order * Doesn\u2019t have a deterministic iteration order * Doesn\u2019t guarantee that an element added during an iteration will be produced during this iteration</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-the-break-statement-works-34","title":"Ignoring how the <code>break</code> statement works (#34)","text":"<p>TL;DR: Using <code>break</code> or <code>continue</code> with a label enforces breaking a specific statement. This can be helpful with <code>switch</code> or <code>select</code> statements inside loops.</p> <p>A break statement is commonly used to terminate the execution of a loop. When loops are used in conjunction with switch or select, developers frequently make the mistake of breaking the wrong statement. For example:</p> <pre><code>for i := 0; i &lt; 5; i++ {\n    fmt.Printf(\"%d \", i)\n\n    switch i {\n    default:\n    case 2:\n        break\n    }\n}\n</code></pre> <p>The break statement doesn\u2019t terminate the <code>for</code> loop: it terminates the <code>switch</code> statement, instead. Hence, instead of iterating from 0 to 2, this code iterates from 0 to 4: <code>0 1 2 3 4</code>.</p> <p>One essential rule to keep in mind is that a <code>break</code> statement terminates the execu- tion of the innermost <code>for</code>, <code>switch</code>, or <code>select</code> statement. In the previous example, it terminates the <code>switch</code> statement.</p> <p>To break the loop instead of the <code>switch</code> statement, the most idiomatic way is to use a label:</p> <pre><code>loop:\n    for i := 0; i &lt; 5; i++ {\n        fmt.Printf(\"%d \", i)\n\n        switch i {\n        default:\n        case 2:\n            break loop\n        }\n    }\n</code></pre> <p>Here, we associate the <code>loop</code> label with the <code>for</code> loop. Then, because we provide the <code>loop</code> label to the <code>break</code> statement, it breaks the loop, not the switch. Therefore, this new version will print <code>0 1 2</code>, as we expected.</p> <p>Source code</p>"},{"location":"mistakes/#using-defer-inside-a-loop-35","title":"Using <code>defer</code> inside a loop (#35)","text":"<p>TL;DR: Extracting loop logic inside a function leads to executing a <code>defer</code> statement at the end of each iteration.</p> <p>The <code>defer</code> statement delays a call\u2019s execution until the surrounding function returns. It\u2019s mainly used to reduce boilerplate code. For example, if a resource has to be closed eventually, we can use <code>defer</code> to avoid repeating the closure calls before every single <code>return</code>.</p> <p>One common mistake with <code>defer</code> is to forget that it schedules a function call when the surrounding function returns. For example:</p> <pre><code>func readFiles(ch &lt;-chan string) error {\n    for path := range ch {\n        file, err := os.Open(path)\n        if err != nil {\n            return err\n        }\n\n        defer file.Close()\n\n        // Do something with file\n    }\n    return nil\n}\n</code></pre> <p>The <code>defer</code> calls are executed not during each loop iteration but when the <code>readFiles</code> function returns. If <code>readFiles</code> doesn\u2019t return, the file descriptors will be kept open forever, causing leaks.</p> <p>One common option to fix this problem is to create a surrounding function after <code>defer</code>, called during each iteration:</p> <pre><code>func readFiles(ch &lt;-chan string) error {\n    for path := range ch {\n        if err := readFile(path); err != nil {\n            return err\n        }\n    }\n    return nil\n}\n\nfunc readFile(path string) error {\n    file, err := os.Open(path)\n    if err != nil {\n        return err\n    }\n\n    defer file.Close()\n\n    // Do something with file\n    return nil\n}\n</code></pre> <p>Another solution is to make the <code>readFile</code> function a closure but intrinsically, this remains the same solution: adding another surrounding function to execute the <code>defer</code> calls during each iteration.</p> <p>Source code</p>"},{"location":"mistakes/#strings","title":"Strings","text":""},{"location":"mistakes/#not-understanding-the-concept-of-rune-36","title":"Not understanding the concept of rune (#36)","text":"<p>TL;DR: Understanding that a rune corresponds to the concept of a Unicode code point and that it can be composed of multiple bytes should be part of the Go developer\u2019s core knowledge to work accurately with strings.</p> <p>As runes are everywhere in Go, it's important to understand the following:</p> <ul> <li>A charset is a set of characters, whereas an encoding describes how to translate a charset into binary.</li> <li>In Go, a string references an immutable slice of arbitrary bytes.</li> <li>Go source code is encoded using UTF-8. Hence, all string literals are UTF-8 strings. But because a string can contain arbitrary bytes, if it\u2019s obtained from somewhere else (not the source code), it isn\u2019t guaranteed to be based on the UTF-8 encoding.</li> <li>A <code>rune</code> corresponds to the concept of a Unicode code point, meaning an item represented by a single value.</li> <li>Using UTF-8, a Unicode code point can be encoded into 1 to 4 bytes.</li> <li>Using <code>len()</code> on a string in Go returns the number of bytes, not the number of runes.</li> </ul> <p>Source code</p>"},{"location":"mistakes/#inaccurate-string-iteration-37","title":"Inaccurate string iteration (#37)","text":"<p>TL;DR: Iterating on a string with the <code>range</code> operator iterates on the runes with the index corresponding to the starting index of the rune\u2019s byte sequence. To access a specific rune index (such as the third rune), convert the string into a <code>[]rune</code>.</p> <p>Iterating on a string is a common operation for developers. Perhaps we want to per- form an operation for each rune in the string or implement a custom function to search for a specific substring. In both cases, we have to iterate on the different runes of a string. But it\u2019s easy to get confused about how iteration works.</p> <p>For example, consider the following example:</p> <pre><code>s := \"h\u00eallo\"\nfor i := range s {\n    fmt.Printf(\"position %d: %c\\n\", i, s[i])\n}\nfmt.Printf(\"len=%d\\n\", len(s))\n</code></pre> <pre><code>position 0: h\nposition 1: \u00c3\nposition 3: l\nposition 4: l\nposition 5: o\nlen=6\n</code></pre> <p>Let's highlight three points that might be confusing:</p> <ul> <li>The second rune is \u00c3 in the output instead of \u00ea.</li> <li>We jumped from position 1 to position 3: what is at position 2?</li> <li>len returns a count of 6, whereas s contains only 5 runes.</li> </ul> <p>Let\u2019s start with the last observation. We already mentioned that len returns the num- ber of bytes in a string, not the number of runes. Because we assigned a string literal to <code>s</code>, <code>s</code> is a UTF-8 string. Meanwhile, the special character \"\u00ea\" isn\u2019t encoded in a single byte; it requires 2 bytes. Therefore, calling <code>len(s)</code> returns 6.</p> <p>Meanwhile, in the previous example, we have to understand that we don't iterate over each rune; instead, we iterate over each starting index of a rune:</p> <p></p> <p>Printing <code>s[i]</code> doesn\u2019t print the ith rune; it prints the UTF-8 representation of the byte at index <code>i</code>. Hence, we printed \"h\u00c3llo\" instead of \"h\u00eallo\".</p> <p>If we want to print all the different runes, we can either use the value element of the <code>range</code> operator:</p> <pre><code>s := \"h\u00eallo\"\nfor i, r := range s {\n    fmt.Printf(\"position %d: %c\\n\", i, r)\n}\n</code></pre> <p>Or, we can convert the string into a slice of runes and iterate over it:</p> <pre><code>s := \"h\u00eallo\"\nrunes := []rune(s)\nfor i, r := range runes {\n    fmt.Printf(\"position %d: %c\\n\", i, r)\n}\n</code></pre> <p>Note that this solution introduces a run-time overhead compared to the previous one. Indeed, converting a string into a slice of runes requires allocating an additional slice and converting the bytes into runes: an O(n) time complexity with n the number of bytes in the string. Therefore, if we want to iterate over all the runes, we should use the first solution.</p> <p>However, if we want to access the ith rune of a string with the first option, we don\u2019t have access to the rune index; rather, we know the starting index of a rune in the byte sequence.</p> <pre><code>s := \"h\u00eallo\"\nr := []rune(s)[4]\nfmt.Printf(\"%c\\n\", r) // o\n</code></pre> <p>Source code</p>"},{"location":"mistakes/#misusing-trim-functions-38","title":"Misusing trim functions (#38)","text":"<p>TL;DR: <code>strings.TrimRight</code>/<code>strings.TrimLeft</code> removes all the trailing/leading runes contained in a given set, whereas <code>strings.TrimSuffix</code>/<code>strings.TrimPrefix</code> returns a string without a provided suffix/prefix.</p> <p>For example:</p> <pre><code>fmt.Println(strings.TrimRight(\"123oxo\", \"xo\"))\n</code></pre> <p>The example prints 123:</p> <p></p> <p>Conversely, <code>strings.TrimLeft</code> removes all the leading runes contained in a set.</p> <p>On the other side, <code>strings.TrimSuffix</code> / <code>strings.TrimPrefix</code> returns a string without the provided trailing suffix / prefix.</p> <p>Source code</p>"},{"location":"mistakes/#under-optimized-strings-concatenation-39","title":"Under-optimized strings concatenation (#39)","text":"<p>TL;DR: Concatenating a list of strings should be done with <code>strings.Builder</code> to prevent allocating a new string during each iteration.</p> <p>Let\u2019s consider a <code>concat</code> function that concatenates all the string elements of a slice using the <code>+=</code> operator:</p> <pre><code>func concat(values []string) string {\n    s := \"\"\n    for _, value := range values {\n        s += value\n    }\n    return s\n}\n</code></pre> <p>During each iteration, the <code>+=</code> operator concatenates <code>s</code> with the value string. At first sight, this function may not look wrong. But with this implementation, we forget one of the core characteristics of a string: its immutability. Therefore, each iteration doesn\u2019t update <code>s</code>; it reallocates a new string in memory, which significantly impacts the performance of this function.</p> <p>Fortunately, there is a solution to deal with this problem, using <code>strings.Builder</code>:</p> <pre><code>func concat(values []string) string {\n    sb := strings.Builder{}\n    for _, value := range values {\n        _, _ = sb.WriteString(value)\n    }\n    return sb.String()\n}\n</code></pre> <p>During each iteration, we constructed the resulting string by calling the <code>WriteString</code> method that appends the content of value to its internal buffer, hence minimizing memory copying.</p> <p>[!NOTE] <code>WriteString</code> returns an error as the second output, but we purposely ignore it. Indeed, this method will never return a non-nil error. So what\u2019s the purpose of this method returning an error as part of its signature? <code>strings.Builder</code> imple- ments the <code>io.StringWriter</code> interface, which contains a single method: <code>WriteString(s string) (n int, err error)</code>. Hence, to comply with this interface, <code>WriteString</code> must return an error.</p> <p>Internally, <code>strings.Builder</code> holds a byte slice. Each call to <code>WriteString</code> results in a call to append on this slice. There are two impacts. First, this struct shouldn\u2019t be used concurrently, as the calls to <code>append</code> would lead to race conditions. The second impact is something that we saw in mistake #21, \"Inefficient slice initialization\": if the future length of a slice is already known, we should preallocate it. For that purpose, <code>strings.Builder</code> exposes a method <code>Grow(n int)</code> to guarantee space for another <code>n</code> bytes:</p> <pre><code>func concat(values []string) string {\n    total := 0\n    for i := 0; i &lt; len(values); i++ {\n        total += len(values[i])\n    }\n\n    sb := strings.Builder{}\n    sb.Grow(total) (2)\n    for _, value := range values {\n        _, _ = sb.WriteString(value)\n    }\n    return sb.String()\n}\n</code></pre> <p>Let\u2019s run a benchmark to compare the three versions (v1 using <code>+=</code>; v2 using <code>strings.Builder{}</code> without preallocation; and v3 using <code>strings.Builder{}</code> with pre- allocation). The input slice contains 1,000 strings, and each string contains 1,000 bytes:</p> <pre><code>BenchmarkConcatV1-4             16      72291485 ns/op\nBenchmarkConcatV2-4           1188        878962 ns/op\nBenchmarkConcatV3-4           5922        190340 ns/op\n</code></pre> <p>As we can see, the latest version is by far the most efficient: 99% faster than v1 and 78% faster than v2.</p> <p><code>strings.Builder</code> is the recommended solution to concatenate a list of strings. Usually, this solution should be used within a loop. Indeed, if we just have to concate- nate a few strings (such as a name and a surname), using <code>strings.Builder</code> is not rec- ommended as doing so will make the code a bit less readable than using the <code>+=</code> operator or <code>fmt.Sprintf</code>.</p> <p>Source code</p>"},{"location":"mistakes/#useless-string-conversions-40","title":"Useless string conversions (#40)","text":"<p>TL;DR: Remembering that the <code>bytes</code> package offers the same operations as the <code>strings</code> package can help avoid extra byte/string conversions.</p> <p>When choosing to work with a string or a <code>[]byte</code>, most programmers tend to favor strings for convenience. But most I/O is actually done with <code>[]byte</code>. For example, <code>io.Reader</code>, <code>io.Writer</code>, and <code>io.ReadAll</code> work with <code>[]byte</code>, not strings.</p> <p>When we\u2019re wondering whether we should work with strings or <code>[]byte</code>, let\u2019s recall that working with <code>[]byte</code> isn\u2019t necessarily less convenient. Indeed, all the exported functions of the strings package also have alternatives in the <code>bytes</code> package: <code>Split</code>, <code>Count</code>, <code>Contains</code>, <code>Index</code>, and so on. Hence, whether we\u2019re doing I/O or not, we should first check whether we could implement a whole workflow using bytes instead of strings and avoid the price of additional conversions.</p> <p>Source code</p>"},{"location":"mistakes/#substring-and-memory-leaks-41","title":"Substring and memory leaks (#41)","text":"<p>TL;DR: Using copies instead of substrings can prevent memory leaks, as the string returned by a substring operation will be backed by the same byte array.</p> <p>In mistake #26, \u201cSlices and memory leaks,\u201d we saw how slicing a slice or array may lead to memory leak situations. This principle also applies to string and substring opera- tions.</p> <p>We need to keep two things in mind while using the substring operation in Go. First, the interval provided is based on the number of bytes, not the number of runes. Second, a substring operation may lead to a memory leak as the resulting substring will share the same backing array as the initial string. The solutions to prevent this case from happening are to perform a string copy manually or to use <code>strings.Clone</code> from Go 1.18.</p> <p>Source code</p>"},{"location":"mistakes/#functions-and-methods","title":"Functions and Methods","text":""},{"location":"mistakes/#not-knowing-which-type-of-receiver-to-use-42","title":"Not knowing which type of receiver to use (#42)","text":"<p>TL;DR: The decision whether to use a value or a pointer receiver should be made based on factors such as the type, whether it has to be mutated, whether it contains a field that can\u2019t be copied, and how large the object is. When in doubt, use a pointer receiver.</p> <p>Choosing between value and pointer receivers isn\u2019t always straightforward. Let\u2019s dis- cuss some of the conditions to help us choose.</p> <p>A receiver must be a pointer</p> <ul> <li>If the method needs to mutate the receiver. This rule is also valid if the receiver is a slice and a method needs to append elements:</li> </ul> <p>```cgo   type slice []int</p> <p>func (s slice) add(element int) {             s = append(*s, element)   }   ```</p> <ul> <li>If the method receiver contains a field that cannot be copied: for example, a type part of the sync package (see #74, \u201cCopying a sync type\u201d).</li> </ul> <p>A receiver should be a pointer</p> <ul> <li>If the receiver is a large object. Using a pointer can make the call more effi- cient, as doing so prevents making an extensive copy. When in doubt about how large is large, benchmarking can be the solution; it\u2019s pretty much impossible to state a specific size, because it depends on many factors.</li> </ul> <p>A receiver must be a value</p> <ul> <li>If we have to enforce a receiver\u2019s immutability.</li> <li>If the receiver is a map, function, or channel. Otherwise, a compilation error   occurs.</li> </ul> <p>A receiver should be a value</p> <ul> <li>If the receiver is a slice that doesn\u2019t have to be mutated.</li> <li>If the receiver is a small array or struct that is naturally a value type without mutable fields, such as <code>time.Time</code>.</li> <li>If the receiver is a basic type such as <code>int</code>, <code>float64</code>, or <code>string</code>.</li> </ul> <p>Of course, it\u2019s impossible to be exhaustive, as there will always be edge cases, but this section\u2019s goal was to provide guidance to cover most cases. By default, we can choose to go with a value receiver unless there\u2019s a good reason not to do so. In doubt, we should use a pointer receiver.</p> <p>Source code</p>"},{"location":"mistakes/#never-using-named-result-parameters-43","title":"Never using named result parameters (#43)","text":"<p>TL;DR: Using named result parameters can be an efficient way to improve the readability of a function/method, especially if multiple result parameters have the same type. In some cases, this approach can also be convenient because named result parameters are initialized to their zero value. But be cautious about potential side effects.</p> <p>When we return parameters in a function or a method, we can attach names to these parameters and use them as regular variables. When a result parameter is named, it\u2019s initialized to its zero value when the function/method begins. With named result parameters, we can also call a naked return statement (without argu- ments). In that case, the current values of the result parameters are used as the returned values.</p> <p>Here\u2019s an example that uses a named result parameter <code>b</code>:</p> <pre><code>func f(a int) (b int) {\n    b = a\n    return\n}\n</code></pre> <p>In this example, we attach a name to the result parameter: <code>b</code>. When we call return without arguments, it returns the current value of <code>b</code>.</p> <p>In some cases, named result parameters can also increase readability: for example, if two parameters have the same type. In other cases, they can also be used for convenience. Therefore, we should use named result parameters sparingly when there\u2019s a clear benefit.</p> <p>Source code</p>"},{"location":"mistakes/#unintended-side-effects-with-named-result-parameters-44","title":"Unintended side effects with named result parameters (#44)","text":"<p>TL;DR: See #43.</p> <p>We mentioned why named result parameters can be useful in some situations. But as these result parameters are initialized to their zero value, using them can sometimes lead to subtle bugs if we\u2019re not careful enough. For example, can you spot what\u2019s wrong with this code?</p> <pre><code>func (l loc) getCoordinates(ctx context.Context, address string) (\n    lat, lng float32, err error) {\n    isValid := l.validateAddress(address) (1)\n    if !isValid {\n        return 0, 0, errors.New(\"invalid address\")\n    }\n\n    if ctx.Err() != nil { (2)\n        return 0, 0, err\n    }\n\n    // Get and return coordinates\n}\n</code></pre> <p>The error might not be obvious at first glance. Here, the error returned in the <code>if ctx.Err() != nil</code> scope is <code>err</code>. But we haven\u2019t assigned any value to the <code>err</code> variable. It\u2019s still assigned to the zero value of an <code>error</code> type: <code>nil</code>. Hence, this code will always return a nil error.</p> <p>When using named result parameters, we must recall that each parameter is initial- ized to its zero value. As we have seen in this section, this can lead to subtle bugs that aren\u2019t always straightforward to spot while reading code. Therefore, let\u2019s remain cau- tious when using named result parameters, to avoid potential side effects.</p> <p>Source code</p>"},{"location":"mistakes/#returning-a-nil-receiver-45","title":"Returning a nil receiver (#45)","text":"<p>TL;DR: When returning an interface, be cautious about returning not a nil pointer but an explicit nil value. Otherwise, unintended consequences may result because the caller will receive a non-nil value.</p> <p>Source code</p>"},{"location":"mistakes/#using-a-filename-as-a-function-input-46","title":"Using a filename as a function input (#46)","text":"<p>TL;DR: Designing functions to receive <code>io.Reader</code> types instead of filenames improves the reusability of a function and makes testing easier.</p> <p>Accepting a filename as a function input to read from a file should, in most cases, be considered a code smell (except in specific functions such as <code>os.Open</code>). Indeed, it makes unit tests more complex because we may have to create multiple files. It also reduces the reusability of a function (although not all functions are meant to be reused). Using the <code>io.Reader</code> interface abstracts the data source. Regardless of whether the input is a file, a string, an HTTP request, or a gRPC request, the imple- mentation can be reused and easily tested.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-defer-arguments-and-receivers-are-evaluated-argument-evaluation-pointer-and-value-receivers-47","title":"Ignoring how <code>defer</code> arguments and receivers are evaluated (argument evaluation, pointer, and value receivers) (#47)","text":"<p>TL;DR: Passing a pointer to a <code>defer</code> function and wrapping a call inside a closure are two possible solutions to overcome the immediate evaluation of arguments and receivers.</p> <p>In a <code>defer</code> function the arguments are evaluated right away, not once the surrounding function returns. For example, in this code, we always call <code>notify</code> and <code>incrementCounter</code> with the same status: an empty string.</p> <pre><code>const (\n    StatusSuccess  = \"success\"\n    StatusErrorFoo = \"error_foo\"\n    StatusErrorBar = \"error_bar\"\n)\n\nfunc f() error {\n    var status string\n    defer notify(status)\n    defer incrementCounter(status)\n\n    if err := foo(); err != nil {\n        status = StatusErrorFoo\n        return err\n    }\n\n    if err := bar(); err != nil {\n        status = StatusErrorBar\n        return err\n    }\n\n    status = StatusSuccess &lt;5&gt;\n    return nil\n}\n</code></pre> <p>Indeed, we call <code>notify(status)</code> and <code>incrementCounter(status)</code> as <code>defer</code> functions. Therefore, Go will delay these calls to be executed once <code>f</code> returns with the current value of status at the stage we used defer, hence passing an empty string.</p> <p>Two leading options if we want to keep using <code>defer</code>.</p> <p>The first solution is to pass a string pointer:</p> <pre><code>func f() error {\n    var status string\n    defer notify(&amp;status) \n    defer incrementCounter(&amp;status)\n\n    // The rest of the function unchanged\n    if err := foo(); err != nil {\n        status = StatusErrorFoo\n        return err\n    }\n\n    if err := bar(); err != nil {\n        status = StatusErrorBar\n        return err\n    }\n\n    status = StatusSuccess\n    return nil\n}\n</code></pre> <p>Using <code>defer</code> evaluates the arguments right away: here, the address of status. Yes, status itself is modified throughout the function, but its address remains constant, regardless of the assignments. Hence, if <code>notify</code> or <code>incrementCounter</code> uses the value referenced by the string pointer, it will work as expected. But this solution requires changing the signature of the two functions, which may not always be possible.</p> <p>There\u2019s another solution: calling a closure (an anonymous function value that references variables from outside its body) as a <code>defer</code> statement:</p> <pre><code>func f() error {\n    var status string\n    defer func() {\n        notify(status)\n        incrementCounter(status)\n    }()\n\n    // The rest of the function unchanged\n}\n</code></pre> <p>Here, we wrap the calls to both <code>notify</code> and <code>incrementCounter</code> within a closure. This closure references the status variable from outside its body. Therefore, <code>status</code> is evaluated once the closure is executed, not when we call <code>defer</code>. This solution also works and doesn\u2019t require <code>notify</code> and <code>incrementCounter</code> to change their signature.</p> <p>Let's also note this behavior applies with method receiver: the receiver is evaluated immediately.</p> <p>Source code</p>"},{"location":"mistakes/#error-management","title":"Error Management","text":""},{"location":"mistakes/#panicking-48","title":"Panicking (#48)","text":"<p>TL;DR: Using <code>panic</code> is an option to deal with errors in Go. However, it should only be used sparingly in unrecoverable conditions: for example, to signal a programmer error or when you fail to load a mandatory dependency.</p> <p>In Go, panic is a built-in function that stops the ordinary flow:</p> <pre><code>func main() {\n    fmt.Println(\"a\")\n    panic(\"foo\")\n    fmt.Println(\"b\")\n}\n</code></pre> <p>This code prints a and then stops before printing b:</p> <pre><code>a\npanic: foo\n\ngoroutine 1 [running]:\nmain.main()\n        main.go:7 +0xb3\n</code></pre> <p>Panicking in Go should be used sparingly. There are two prominent cases, one to signal a programmer error (e.g., <code>sql.Register</code> that panics if the driver is <code>nil</code> or has already been register) and another where our application fails to create a man- datory dependency. Hence, exceptional conditions that lead us to stop the application. In most other cases, error management should be done with a function that returns a proper error type as the last return argument.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-when-to-wrap-an-error-49","title":"Ignoring when to wrap an error (#49)","text":"<p>TL;DR: Wrapping an error allows you to mark an error and/or provide additional context. However, error wrapping creates potential coupling as it makes the source error available for the caller. If you want to prevent that, don\u2019t use error wrapping.</p> <p>Since Go 1.13, the %w directive allows us to wrap errors conveniently. Error wrapping is about wrapping or packing an error inside a wrapper container that also makes the source error available. In general, the two main use cases for error wrapping are the following:</p> <ul> <li>Adding additional context to an error</li> <li>Marking an error as a specific error</li> </ul> <p>When handling an error, we can decide to wrap it. Wrapping is about adding additional context to an error and/or marking an error as a specific type. If we need to mark an error, we should create a custom error type. However, if we just want to add extra context, we should use fmt.Errorf with the %w directive as it doesn\u2019t require creating a new error type. Yet, error wrapping creates potential coupling as it makes the source error available for the caller. If we want to prevent it, we shouldn\u2019t use error wrapping but error transformation, for example, using fmt.Errorf with the %v directive.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-an-error-type-inaccurately-50","title":"Comparing an error type inaccurately (#50)","text":"<p>TL;DR: If you use Go 1.13 error wrapping with the <code>%w</code> directive and <code>fmt.Errorf</code>, comparing an error against a type has to be done using <code>errors.As</code>. Otherwise, if the returned error you want to check is wrapped, it will fail the checks.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-an-error-value-inaccurately-51","title":"Comparing an error value inaccurately (#51)","text":"<p>TL;DR: If you use Go 1.13 error wrapping with the <code>%w</code> directive and <code>fmt.Errorf</code>, comparing an error against or a value has to be done using <code>errors.As</code>. Otherwise, if the returned error you want to check is wrapped, it will fail the checks.</p> <p>A sentinel error is an error defined as a global variable:</p> <pre><code>import \"errors\"\n\nvar ErrFoo = errors.New(\"foo\")\n</code></pre> <p>In general, the convention is to start with <code>Err</code> followed by the error type: here, <code>ErrFoo</code>. A sentinel error conveys an expected error, an error that clients will expect to check. As general guidelines:</p> <ul> <li>Expected errors should be designed as error values (sentinel errors): <code>var ErrFoo = errors.New(\"foo\")</code>.</li> <li>Unexpected errors should be designed as error types: <code>type BarError struct { ... }</code>, with <code>BarError</code> implementing the <code>error</code> interface.</li> </ul> <p>If we use error wrapping in our application with the <code>%w</code> directive and <code>fmt.Errorf</code>, checking an error against a specific value should be done using <code>errors.Is</code> instead of <code>==</code>. Thus, even if the sentinel error is wrapped, <code>errors.Is</code> can recursively unwrap it and compare each error in the chain against the provided value.</p> <p>Source code</p>"},{"location":"mistakes/#handling-an-error-twice-52","title":"Handling an error twice (#52)","text":"<p>TL;DR: In most situations, an error should be handled only once. Logging an error is handling an error. Therefore, you have to choose between logging or returning an error. In many cases, error wrapping is the solution as it allows you to provide additional context to an error and return the source error.</p> <p>Handling an error multiple times is a mistake made frequently by developers, not spe- cifically in Go. This can cause situations where the same error is logged multiple times make debugging harder.</p> <p>Let's reming us that handling an error should be done only once. Logging an error is handling an error. Hence, we should either log or return an error. By doing this, we simplify our code and gain better insights into the error situation. Using error wrap- ping is the most convenient approach as it allows us to propagate the source error and add context to an error.</p> <p>Source code</p>"},{"location":"mistakes/#not-handling-an-error-53","title":"Not handling an error (#53)","text":"<p>TL;DR: Ignoring an error, whether during a function call or in a <code>defer</code> function, should be done explicitly using the blank identifier. Otherwise, future readers may be confused about whether it was intentional or a miss.</p> <p>Source code</p>"},{"location":"mistakes/#not-handling-defer-errors-54","title":"Not handling <code>defer</code> errors (#54)","text":"<p>TL;DR: In many cases, you shouldn\u2019t ignore an error returned by a <code>defer</code> function. Either handle it directly or propagate it to the caller, depending on the context. If you want to ignore it, use the blank identifier.</p> <p>Consider the following code:</p> <pre><code>func f() {\n  // ...\n  notify() // Error handling is omitted\n}\n\nfunc notify() error {\n  // ...\n}\n</code></pre> <p>From a maintainability perspective, the code can lead to some issues. Let\u2019s consider a new reader looking at it. This reader notices that notify returns an error but that the error isn\u2019t handled by the parent function. How can they guess whether or not handling the error was intentional? How can they know whether the previous developer forgot to handle it or did it purposely?</p> <p>For these reasons, when we want to ignore an error, there's only one way to do it, using the blank identifier (<code>_</code>):</p> <pre><code>_ = notify\n</code></pre> <p>In terms of compilation and run time, this approach doesn\u2019t change anything compared to the first piece of code. But this new version makes explicit that we aren\u2019t interested in the error. Also, we can add a comment that indicates the rationale for why an error is ignored:</p> <pre><code>// At-most once delivery.\n// Hence, it's accepted to miss some of them in case of errors.\n_ = notify()\n</code></pre> <p>Source code</p>"},{"location":"mistakes/#concurrency-foundations","title":"Concurrency: Foundations","text":""},{"location":"mistakes/#mixing-up-concurrency-and-parallelism-55","title":"Mixing up concurrency and parallelism (#55)","text":"<p>TL;DR: Understanding the fundamental differences between concurrency and parallelism is a cornerstone of the Go developer\u2019s knowledge. Concurrency is about structure, whereas parallelism is about execution.</p>"},{"location":"mistakes/#thinking-concurrency-is-always-faster-56","title":"Thinking concurrency is always faster (#56)","text":"<p>TL;DR: To be a proficient developer, you must acknowledge that concurrency isn\u2019t always faster. Solutions involving parallelization of minimal workloads may not necessarily be faster than a sequential implementation. Benchmarking sequential versus concurrent solutions should be the way to validate assumptions.</p> <p>Source code</p>"},{"location":"mistakes/#being-puzzled-about-when-to-use-channels-or-mutexes-57","title":"Being puzzled about when to use channels or mutexes (#57)","text":"<p>TL;DR: Being aware of goroutine interactions can also be helpful when deciding between channels and mutexes. In general, parallel goroutines require synchronization and hence mutexes. Conversely, concurrent goroutines generally require coordination and orchestration and hence channels.</p>"},{"location":"mistakes/#not-understanding-race-problems-data-races-vs-race-conditions-and-the-go-memory-model-58","title":"Not understanding race problems (data races vs. race conditions and the Go memory model) (#58)","text":"<p>TL;DR: Being proficient in concurrency also means understanding that data races and race conditions are different concepts. Data races occur when multiple goroutines simultaneously access the same memory location and at least one of them is writing. Meanwhile, being data-race-free doesn\u2019t necessarily mean deterministic execution. When a behavior depends on the sequence or the timing of events that can\u2019t be controlled, this is a race condition.</p> <p>Understanding the Go memory model and the underlying guarantees in terms of ordering and synchronization is essential to prevent possible data races and/or race conditions.</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-the-concurrency-impacts-of-a-workload-type-59","title":"Not understanding the concurrency impacts of a workload type (#59)","text":"<p>TL;DR: When creating a certain number of goroutines, consider the workload type. Creating CPU-bound goroutines means bounding this number close to the <code>GOMAXPROCS</code> variable (based by default on the number of CPU cores on the host). Creating I/O-bound goroutines depends on other factors, such as the external system.</p> <p>Source code</p>"},{"location":"mistakes/#misunderstanding-go-contexts-60","title":"Misunderstanding Go contexts (#60)","text":"<p>TL;DR: Go contexts are also one of the cornerstones of concurrency in Go. A context allows you to carry a deadline, a cancellation signal, and/or a list of keys-values.</p> <p>Source code</p>"},{"location":"mistakes/#concurrency-practice","title":"Concurrency: Practice","text":""},{"location":"mistakes/#propagating-an-inappropriate-context-61","title":"Propagating an inappropriate context (#61)","text":"<p>TL;DR: Understanding the conditions when a context can be canceled should matter when propagating it: for example, an HTTP handler canceling the context when the response has been sent.</p> <p>Source code</p>"},{"location":"mistakes/#starting-a-goroutine-without-knowing-when-to-stop-it-62","title":"Starting a goroutine without knowing when to stop it (#62)","text":"<p>TL;DR: Avoiding leaks means being mindful that whenever a goroutine is started, you should have a plan to stop it eventually.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-careful-with-goroutines-and-loop-variables-63","title":"Not being careful with goroutines and loop variables (#63)","text":"<p>TL;DR: To avoid bugs with goroutines and loop variables, create local variables or call functions instead of closures.</p> <p>Source code</p>"},{"location":"mistakes/#expecting-a-deterministic-behavior-using-select-and-channels-64","title":"Expecting a deterministic behavior using select and channels (#64)","text":"<p>TL;DR: Understanding that <code>select</code> with multiple channels chooses the case randomly if multiple options are possible prevents making wrong assumptions that can lead to subtle concurrency bugs.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-notification-channels-65","title":"Not using notification channels (#65)","text":"<p>TL;DR: Send notifications using a <code>chan struct{}</code> type.</p>"},{"location":"mistakes/#not-using-nil-channels-66","title":"Not using nil channels (#66)","text":"<p>TL;DR: Using nil channels should be part of your concurrency toolset because it allows you to remove cases from <code>select</code> statements, for example.</p> <p>Source code</p>"},{"location":"mistakes/#being-puzzled-about-channel-size-67","title":"Being puzzled about channel size (#67)","text":"<p>TL;DR: Carefully decide on the right channel type to use, given a problem. Only unbuffered channels provide strong synchronization guarantees.</p> <p>You should have a good reason to specify a channel size other than one for buffered channels.</p>"},{"location":"mistakes/#forgetting-about-possible-side-effects-with-string-formatting-etcd-data-race-example-and-deadlock-68","title":"Forgetting about possible side effects with string formatting (etcd data race example and deadlock) (#68)","text":"<p>TL;DR: Being aware that string formatting may lead to calling existing functions means watching out for possible deadlocks and other data races.</p> <p>Source code</p>"},{"location":"mistakes/#creating-data-races-with-append-69","title":"Creating data races with append (#69)","text":"<p>TL;DR: Calling <code>append</code> isn\u2019t always data-race-free; hence, it shouldn\u2019t be used concurrently on a shared slice.</p> <p>Source code</p>"},{"location":"mistakes/#using-mutexes-inaccurately-with-slices-and-maps-70","title":"Using mutexes inaccurately with slices and maps (#70)","text":"<p>TL;DR: Remembering that slices and maps are pointers can prevent common data races.</p> <p>Source code</p>"},{"location":"mistakes/#misusing-syncwaitgroup-71","title":"Misusing <code>sync.WaitGroup</code> (#71)","text":"<p>TL;DR: To accurately use <code>sync.WaitGroup</code>, call the <code>Add</code> method before spinning up goroutines.</p> <p>Source code</p>"},{"location":"mistakes/#forgetting-about-synccond-72","title":"Forgetting about <code>sync.Cond</code> (#72)","text":"<p>TL;DR: You can send repeated notifications to multiple goroutines with <code>sync.Cond</code>.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-errgroup-73","title":"Not using <code>errgroup</code> (#73)","text":"<p>TL;DR: You can synchronize a group of goroutines and handle errors and contexts with the <code>errgroup</code> package.</p> <p>Source code</p>"},{"location":"mistakes/#copying-a-sync-type-74","title":"Copying a <code>sync</code> type (#74)","text":"<p>TL;DR: <code>sync</code> types shouldn\u2019t be copied.</p> <p>Source code</p>"},{"location":"mistakes/#standard-library","title":"Standard Library","text":""},{"location":"mistakes/#providing-a-wrong-time-duration-75","title":"Providing a wrong time duration (#75)","text":"<p>TL;DR: Remain cautious with functions accepting a <code>time.Duration</code>. Even though passing an integer is allowed, strive to use the time API to prevent any possible confusion.</p> <p>Source code</p>"},{"location":"mistakes/#timeafter-and-memory-leaks-76","title":"<code>time.After</code> and memory leaks (#76)","text":"<p>TL;DR: Avoiding calls to <code>time.After</code> in repeated functions (such as loops or HTTP handlers) can avoid peak memory consumption. The resources created by <code>time.After</code> are released only when the timer expires.</p> <p>Source code</p>"},{"location":"mistakes/#json-handling-common-mistakes-77","title":"JSON handling common mistakes (#77)","text":"<ul> <li>Unexpected behavior because of type embedding</li> </ul> <p>Be careful about using embedded fields in Go structs. Doing so may lead to sneaky bugs like an embedded time.Time field implementing the <code>json.Marshaler</code> interface, hence overriding the default marshaling behavior.</p> <p>Source code</p> <ul> <li>JSON and the monotonic clock</li> </ul> <p>When comparing two <code>time.Time</code> structs, recall that <code>time.Time</code> contains both a wall clock and a monotonic clock, and the comparison using the == operator is done on both clocks.</p> <p>Source code</p> <ul> <li>Map of <code>any</code></li> </ul> <p>To avoid wrong assumptions when you provide a map while unmarshaling JSON data, remember that numerics are converted to <code>float64</code> by default.</p> <p>Source code</p>"},{"location":"mistakes/#common-sql-mistakes-78","title":"Common SQL mistakes (#78)","text":"<ul> <li>Forgetting that <code>sql.Open</code> doesn't necessarily establish connections to a database</li> </ul> <p>Call the <code>Ping</code> or <code>PingContext</code> method if you need to test your configuration and make sure a database is reachable.</p> <p>Source code</p> <ul> <li>Forgetting about connections pooling</li> </ul> <p>Configure the database connection parameters for production-grade applications.</p> <ul> <li>Not using prepared statements</li> </ul> <p>Using SQL prepared statements makes queries more efficient and more secure.</p> <p>Source code</p> <ul> <li>Mishandling null values</li> </ul> <p>Deal with nullable columns in tables using pointers or <code>sql.NullXXX</code> types.</p> <p>Source code</p> <ul> <li>Not handling rows iteration errors</li> </ul> <p>Call the <code>Err</code> method of <code>sql.Rows</code> after row iterations to ensure that you haven\u2019t missed an error while preparing the next row.</p> <p>Source code</p>"},{"location":"mistakes/#not-closing-transient-resources-http-body-sqlrows-and-osfile-79","title":"Not closing transient resources (HTTP body, <code>sql.Rows</code>, and <code>os.File</code>) (#79)","text":"<p>TL;DR: Eventually close all structs implementing <code>io.Closer</code> to avoid possible leaks.</p> <p>Source code</p>"},{"location":"mistakes/#forgetting-the-return-statement-after-replying-to-an-http-request-80","title":"Forgetting the return statement after replying to an HTTP request (#80)","text":"<p>TL;DR: To avoid unexpected behaviors in HTTP handler implementations, make sure you don\u2019t miss the <code>return</code> statement if you want a handler to stop after <code>http.Error</code>.</p> <p>Source code</p>"},{"location":"mistakes/#using-the-default-http-client-and-server-81","title":"Using the default HTTP client and server (#81)","text":"<p>TL;DR: For production-grade applications, don\u2019t use the default HTTP client and server implementations. These implementations are missing timeouts and behaviors that should be mandatory in production.</p> <p>Source code</p>"},{"location":"mistakes/#testing","title":"Testing","text":""},{"location":"mistakes/#not-categorizing-tests-build-tags-environment-variables-and-short-mode-82","title":"Not categorizing tests (build tags, environment variables, and short mode) (#82)","text":"<p>TL;DR: Categorizing tests using build flags, environment variables, or short mode makes the testing process more efficient. You can create test categories using build flags or environment variables (for example, unit versus integration tests) and differentiate short from long-running tests to decide which kinds of tests to execute.</p> <p>Source code</p>"},{"location":"mistakes/#not-enabling-the-race-flag-83","title":"Not enabling the race flag (#83)","text":"<p>TL;DR: Enabling the <code>-race</code> flag is highly recommended when writing concurrent applications. Doing so allows you to catch potential data races that can lead to software bugs.</p>"},{"location":"mistakes/#not-using-test-execution-modes-parallel-and-shuffle-84","title":"Not using test execution modes (parallel and shuffle) (#84)","text":"<p>TL;DR: Using the <code>-parallel</code> flag is an efficient way to speed up tests, especially long-running ones. Use the <code>-shuffle</code> flag to help ensure that a test suite doesn\u2019t rely on wrong assumptions that could hide bugs.</p>"},{"location":"mistakes/#not-using-table-driven-tests-85","title":"Not using table-driven tests (#85)","text":"<p>TL;DR: Table-driven tests are an efficient way to group a set of similar tests to prevent code duplication and make future updates easier to handle.</p> <p>Source code</p>"},{"location":"mistakes/#sleeping-in-unit-tests-86","title":"Sleeping in unit tests (#86)","text":"<p>TL;DR: Avoid sleeps using synchronization to make a test less flaky and more robust. If synchronization isn\u2019t possible, consider a retry approach.</p> <p>Source code</p>"},{"location":"mistakes/#not-dealing-with-the-time-api-efficiently-87","title":"Not dealing with the time API efficiently (#87)","text":"<p>TL;DR: Understanding how to deal with functions using the time API is another way to make a test less flaky. You can use standard techniques such as handling the time as part of a hidden dependency or asking clients to provide it.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-testing-utility-packages-httptest-and-iotest-88","title":"Not using testing utility packages (<code>httptest</code> and <code>iotest</code>) (#88)","text":"<ul> <li>The <code>httptest</code> package is helpful for dealing with HTTP applications. It provides a set of utilities to test both clients and servers.</li> </ul> <p>Source code</p> <ul> <li>The <code>iotest</code> package helps write io.Reader and test that an application is tolerant to errors.</li> </ul> <p>Source code</p>"},{"location":"mistakes/#writing-inaccurate-benchmarks-89","title":"Writing inaccurate benchmarks (#89)","text":"<ul> <li>Not resetting or pausing the timer</li> </ul> <p>Use time methods to preserve the accuracy of a benchmark.</p> <p>Source code</p> <ul> <li>Making wrong assumptions about micro-benchmarks</li> </ul> <p>Increasing <code>benchtime</code> or using tools such as <code>benchstat</code> can be helpful when dealing with micro-benchmarks.</p> <p>Be careful with the results of a micro-benchmark if the system that ends up running the application is different from the one running the micro-benchmark.</p> <p>Source code</p> <ul> <li>Not being careful about compiler optimizations</li> </ul> <p>Make sure the function under test leads to a side effect, to prevent compiler optimizations from fooling you about the benchmark results.</p> <p>Source code</p> <ul> <li>Being fooled by the observer effect</li> </ul> <p>To prevent the observer effect, force a benchmark to re-create the data used by a CPU-bound function.</p> <p>Source code</p>"},{"location":"mistakes/#not-exploring-all-the-go-testing-features-90","title":"Not exploring all the Go testing features (#90)","text":"<ul> <li>Code coverage</li> </ul> <p>Use code coverage with the <code>-coverprofile</code> flag to quickly see which part of the code needs more attention.</p> <ul> <li>Testing from a different package</li> </ul> <p>Place unit tests in a different package to enforce writing tests that focus on an exposed behavior, not internals.</p> <p>Source code</p> <ul> <li>Utility functions</li> </ul> <p>Handling errors using the <code>*testing.T</code> variable instead of the classic <code>if err != nil</code> makes code shorter and easier to read.</p> <p>Source code</p> <ul> <li>Setup and teardown</li> </ul> <p>You can use setup and teardown functions to configure a complex environment, such as in the case of integration tests.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-fuzzing-community-mistake","title":"Not using fuzzing (community mistake)","text":"<p>TL;DR: Fuzzing is an efficient strategy to detect random, unexpected, or malformed inputs to complex functions and methods in order to discover vulnerabilities, bugs, or even potential crashes.</p> <p>Credits: @jeromedoucet</p>"},{"location":"mistakes/#optimizations","title":"Optimizations","text":""},{"location":"mistakes/#not-understanding-cpu-caches-91","title":"Not understanding CPU caches (#91)","text":"<ul> <li>CPU architecture</li> </ul> <p>Understanding how to use CPU caches is important for optimizing CPU-bound applications because the L1 cache is about 50 to 100 times faster than the main memory.</p> <ul> <li>Cache line</li> </ul> <p>Being conscious of the cache line concept is critical to understanding how to organize data in data-intensive applications. A CPU doesn\u2019t fetch memory word by word; instead, it usually copies a memory block to a 64-byte cache line. To get the most out of each individual cache line, enforce spatial locality.</p> <p>Source code</p> <ul> <li>Slice of structs vs. struct of slices</li> </ul> <p>Source code</p> <ul> <li>Predictability</li> </ul> <p>Making code predictable for the CPU can also be an efficient way to optimize certain functions. For example, a unit or constant stride is predictable for the CPU, but a non-unit stride (for example, a linked list) isn\u2019t predictable.</p> <p>Source code</p> <ul> <li>Cache placement policy</li> </ul> <p>To avoid a critical stride, hence utilizing only a tiny portion of the cache, be aware that caches are partitioned.</p>"},{"location":"mistakes/#writing-concurrent-code-that-leads-to-false-sharing-92","title":"Writing concurrent code that leads to false sharing (#92)","text":"<p>TL;DR: Knowing that lower levels of CPU caches aren\u2019t shared across all the cores helps avoid performance-degrading patterns such as false sharing while writing concurrency code. Sharing memory is an illusion.</p> <p>Source code</p>"},{"location":"mistakes/#not-taking-into-account-instruction-level-parallelism-93","title":"Not taking into account instruction-level parallelism (#93)","text":"<p>TL;DR: Use instruction-level parallelism (ILP) to optimize specific parts of your code to allow a CPU to execute as many parallel instructions as possible. Identifying data hazards is one of the main steps.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-aware-of-data-alignment-94","title":"Not being aware of data alignment (#94)","text":"<p>TL;DR: You can avoid common mistakes by remembering that in Go, basic types are aligned with their own size. For example, keep in mind that reorganizing the fields of a struct by size in descending order can lead to more compact structs (less memory allocation and potentially a better spatial locality).</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-stack-vs-heap-95","title":"Not understanding stack vs. heap (#95)","text":"<p>TL;DR: Understanding the fundamental differences between heap and stack should also be part of your core knowledge when optimizing a Go application. Stack allocations are almost free, whereas heap allocations are slower and rely on the GC to clean the memory.</p> <p>Source code</p>"},{"location":"mistakes/#not-knowing-how-to-reduce-allocations-api-change-compiler-optimizations-and-syncpool-96","title":"Not knowing how to reduce allocations (API change, compiler optimizations, and <code>sync.Pool</code>) (#96)","text":"<p>TL;DR: Reducing allocations is also an essential aspect of optimizing a Go application. This can be done in different ways, such as designing the API carefully to prevent sharing up, understanding the common Go compiler optimizations, and using <code>sync.Pool</code>.</p> <p>Source code</p>"},{"location":"mistakes/#not-relying-on-inlining-97","title":"Not relying on inlining (#97)","text":"<p>TL;DR: Use the fast-path inlining technique to efficiently reduce the amortized time to call a function.</p>"},{"location":"mistakes/#not-using-go-diagnostics-tooling-98","title":"Not using Go diagnostics tooling (#98)","text":"<p>TL;DR: Rely on profiling and the execution tracer to understand how an application performs and the parts to optimize.</p>"},{"location":"mistakes/#not-understanding-how-the-gc-works-99","title":"Not understanding how the GC works (#99)","text":"<p>TL;DR: Understanding how to tune the GC can lead to multiple benefits such as handling sudden load increases more efficiently.</p>"},{"location":"mistakes/#not-understanding-the-impacts-of-running-go-in-docker-and-kubernetes-100","title":"Not understanding the impacts of running Go in Docker and Kubernetes (#100)","text":"<p>TL;DR: To help avoid CPU throttling when deployed in Docker and Kubernetes, keep in mind that Go isn\u2019t CFS-aware.</p>"},{"location":"chinese/presentation/","title":"Presentation","text":"<p>TODO</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udcd6 Book Presentation","text":"<p>Source code and community space of 100 Go Mistakes and How to Avoid Them, published by Manning in 2022.</p> <p></p>"},{"location":"#book-description","title":"Book Description","text":"<p>If you're a Go developer looking to improve your skills, this book is for you. With a focus on practical examples, 100 Go Mistakes and How to Avoid Them covers a wide range of topics from concurrency and error handling to testing and code organization. You'll learn to write more idiomatic, efficient, and maintainable code and become a proficient Go developer.</p>"},{"location":"#quotes","title":"Quotes","text":"<p>This is an exceptional book. Usually, if a book contains either high-quality explanations or is written succinctly, I consider myself lucky to have found it. This one combines these two characteristics, which is super rare. It's another Go book for me and I still had quite a lot of \"a-ha!\" moments while reading it, and all of that without the unnecessary fluff, just straight to the point.</p> <ul> <li>Krystian (Goodreads user)</li> </ul> <p>This should be the required reading for all Golang developers before they touch code in Production... It's the Golang equivalent of the legendary 'Effective Java' by Joshua Bloch.</p> <p>\u2013 Neeraj Shah</p> <p>Not having this will be the 101st mistake a Go programmer could make.</p> <p>\u2013 Anupam Sengupta</p>"},{"location":"#where-to-buy","title":"Where to Buy?","text":"<ul> <li> <p>100 Go Mistakes and How to Avoid Them (\ud83c\uddec\ud83c\udde7 edition: paper, digital, or audiobook)</p> <ul> <li>Manning</li> <li>O\u2019Reilly</li> <li>Amazon: .com, .co.uk, .de, .fr, .in, .co.jp, .es, .it, .com.br</li> </ul> </li> <li> <p>Go\u8a00\u8a9e100Tips \u958b\u767a\u8005\u306b\u3042\u308a\u304c\u3061\u306a\u9593\u9055\u3044\u3078\u306e\u5bfe\u51e6\u6cd5 (\ud83c\uddef\ud83c\uddf5 edition)</p> <ul> <li>Amazon: .co.jp</li> </ul> </li> </ul>"},{"location":"#about-the-author","title":"About the Author","text":"<p>Teiva Harsanyi is a senior software engineer at Google. He has worked in various domains, including insurance, transportation, and safety-critical industries like air traffic management. He is passionate about Go and how to design and implement reliable systems.</p>"},{"location":"#external-resources","title":"External Resources","text":""},{"location":"#english","title":"English","text":"<ul> <li>Book Review: 100 Go Mistakes and How to Avoid Them: Post, YouTube</li> <li>How to make mistakes in Go - Go Time #190: Episode, Spotify</li> <li>8LU - 100% Test Coverage</li> <li>Some Tips I learned from 100 Mistakes in Go</li> <li>What can be summarized from 100 Go Mistakes?</li> </ul>"},{"location":"#chinese","title":"Chinese","text":"<ul> <li>\u6df1\u5ea6\u9605\u8bfb\u4e4b\u300a100 Go Mistakes and How to Avoid Them</li> <li>100 Go Mistakes \u968f\u8bb0</li> <li>\u6211\u4e3a\u4ec0\u4e48\u653e\u5f03Go\u8bed\u8a00\uff1f</li> </ul>"},{"location":"#japanese","title":"Japanese","text":"<ul> <li>\u6700\u8fd1\u8aad\u3093\u3060Go\u8a00\u8a9e\u306e\u672c\u306e\u7d39\u4ecb\uff1a100 Go Mistakes and How to Avoid Them</li> <li>\u300e100 Go Mistakes and How to Avoid Them\u300f\u3092\u8aad\u3080</li> <li>100 Go Mistakes \u968f\u8bb0 - 01 Code and project organization</li> </ul>"},{"location":"#portuguese","title":"Portuguese","text":"<ul> <li>Um \u00d3TIMO livro para programadores Go</li> </ul>"},{"location":"jobs/","title":"\u2764\ufe0f Go Jobs","text":"<p>Is your company hiring? Sponsor this repository and let Go developers know your opportunities in this section (traffic: +400 unique visitor per week).</p> <p>For example:</p>"},{"location":"jobs/#company-remote-usa-96000-to-120000-a-year","title":"[Company] Remote (USA) - $96,000 to $120,000 a year","text":""},{"location":"jobs/#job-description","title":"Job Description","text":"<p>...</p>"},{"location":"jobs/#qualifications","title":"Qualifications","text":"<p>...</p>"},{"location":"mistakes/","title":"\ud83d\udca1 Go Mistakes","text":"<p>This section contains a summary of the 100 mistakes in the book. Meanwhile, it's also a section open to the community. If you believe that a mistake should be added, please create a community mistake issue.</p> <p>Note: You're currently viewing a new version that I'm enriching with significantly more content. Yet, this version is still under development; please be gentle if you find an issue, and feel free to create a PR.</p> <p></p>"},{"location":"mistakes/#code-and-project-organization","title":"Code and Project Organization","text":""},{"location":"mistakes/#unintended-variable-shadowing-1","title":"Unintended variable shadowing (#1)","text":"<p>TL;DR: Avoiding shadowed variables can help prevent mistakes like referencing the wrong variable or confusing readers.</p> <p>Variable shadowing occurs when a variable name is redeclared in an inner block, but this practice is prone to mistakes. Imposing a rule to forbid shadowed variables depends on personal taste. For example, sometimes it can be convenient to reuse an existing variable name like <code>err</code> for errors. Yet, in general, we should remain cautious because we now know that we can face a scenario where the code compiles, but the variable that receives the value is not the one expected.</p> <p>Source code</p>"},{"location":"mistakes/#unnecessary-nested-code-2","title":"Unnecessary nested code (#2)","text":"<p>TL;DR: Avoiding nested levels and keeping the happy path aligned on the left makes building a mental code model easier.</p> <p>In general, the more nested levels a function requires, the more complex it is to read and understand. Let\u2019s see some different applications of this rule to optimize our code for readability:</p> <ul> <li>When an <code>if</code> block returns, we should omit the <code>else</code> block in all cases. For example, we shouldn\u2019t write:</li> </ul> <p><code>go   if foo() {       // ...       return true   } else {       // ...   }</code></p> <p>Instead, we omit the <code>else</code> block like this:</p> <p><code>go   if foo() {       // ...       return true   }   // ...</code> * We can also follow this logic with a non-happy path:</p> <p><code>go   if s != \"\" {       // ...   } else {       return errors.New(\"empty string\")   }</code></p> <p>Here, an empty <code>s</code> represents the non-happy path. Hence, we should flip the   condition like so:</p> <p><code>go   if s == \"\" {       return errors.New(\"empty string\")   }   // ...</code></p> <p>Writing readable code is an important challenge for every developer. Striving to reduce the number of nested blocks, aligning the happy path on the left, and returning as early as possible are concrete means to improve our code\u2019s readability.</p> <p>Source code</p>"},{"location":"mistakes/#misusing-init-functions-3","title":"Misusing init functions (#3)","text":"<p>TL;DR: When initializing variables, remember that init functions have limited error handling and make state handling and testing more complex. In most cases, initializations should be handled as specific functions.</p> <p>An init function is a function used to initialize the state of an application. It takes no arguments and returns no result (a <code>func()</code> function). When a package is initialized, all the constant and variable declarations in the package are evaluated. Then, the init functions are executed.</p> <p>Init functions can lead to some issues: * They can limit error management. * They can complicate how to implement tests (for example, an external dependency must be set up, which may not be necessary for the scope of unit tests). * If the initialization requires us to set a state, that has to be done through global variables.</p> <p>We should be cautious with init functions. They can be helpful in some situations, however, such as defining static configuration. Otherwise, and in most cases, we should handle initializations through ad hoc functions.</p> <p>Source code</p>"},{"location":"mistakes/#overusing-getters-and-setters-4","title":"Overusing getters and setters (#4)","text":"<p>TL;DR: Forcing the use of getters and setters isn\u2019t idiomatic in Go. Being pragmatic and finding the right balance between efficiency and blindly following certain idioms should be the way to go.</p> <p>Data encapsulation refers to hiding the values or state of an object. Getters and setters are means to enable encapsulation by providing exported methods on top of unexported object fields.</p> <p>In Go, there is no automatic support for getters and setters as we see in some languages. It is also considered neither mandatory nor idiomatic to use getters and setters to access struct fields. We shouldn\u2019t overwhelm our code with getters and setters on structs if they don\u2019t bring any value. We should be pragmatic and strive to find the right balance between efficiency and following idioms that are sometimes considered indisputable in other programming paradigms.</p> <p>Remember that Go is a unique language designed for many characteristics, including simplicity. However, if we find a need for getters and setters or, as mentioned, foresee a future need while guaranteeing forward compatibility, there\u2019s nothing wrong with using them.</p>"},{"location":"mistakes/#interface-pollution-5","title":"Interface pollution (#5)","text":"<p>TL;DR: Abstractions should be discovered, not created. To prevent unnecessary complexity, create an interface when you need it and not when you foresee needing it, or if you can at least prove the abstraction to be a valid one.</p> <p>An interface provides a way to specify the behavior of an object. We use interfaces to create common abstractions that multiple objects can implement. What makes Go interfaces so different is that they are satisfied implicitly. There is no explicit keyword like <code>implements</code> to mark that an object <code>X</code> implements interface <code>Y</code>.</p> <p>In general, we can define three main use cases where interfaces are generally considered as bringing value: factoring out a common behavior, creating some decoupling, and restricting a type to a certain behavior. Yet, this list isn't exhaustive and will also depend on the context we face.</p> <p>In many occasions, interfaces are made to create abstractions. And the main caveat when programming meets abstractions is remembering that abstractions should be discovered, not created. What does this mean? It means we shouldn\u2019t start creating abstractions in our code if there is no immediate reason to do so. We shouldn\u2019t design with interfaces but wait for a concrete need. Said differently, we should create an interface when we need it, not when we foresee that we could need it. What\u2019s the main problem if we overuse interfaces? The answer is that they make the code flow more complex. Adding a useless level of indirection doesn\u2019t bring any value; it creates a worthless abstraction making the code more difficult to read, understand, and reason about. If we don\u2019t have a strong reason for adding an interface and it\u2019s unclear how an interface makes a code better, we should challenge this interface\u2019s purpose. Why not call the implementation directly?</p> <p>We should be cautious when creating abstractions in our code (abstractions should be discovered, not created). It\u2019s common for us, software developers, to overengineer our code by trying to guess what the perfect level of abstraction is, based on what we think we might need later. This process should be avoided because, in most cases, it pollutes our code with unnecessary abstractions, making it more complex to read.</p> <p>Don\u2019t design with interfaces, discover them.</p> <p>\u2013  Rob Pike</p> <p>Let\u2019s not try to solve a problem abstractly but solve what has to be solved now. Last, but not least, if it\u2019s unclear how an interface makes the code better, we should probably consider removing it to make our code simpler.</p> <p>Source code</p>"},{"location":"mistakes/#interface-on-the-producer-side-6","title":"Interface on the producer side (#6)","text":"<p>TL;DR: Keeping interfaces on the client side avoids unnecessary abstractions.</p> <p>Interfaces are satisfied implicitly in Go, which tends to be a gamechanger compared to languages with an explicit implementation. In most cases, the approach to follow is similar to what we described in the previous section: abstractions should be discovered, not created. This means that it\u2019s not up to the producer to force a given abstraction for all the clients. Instead, it\u2019s up to the client to decide whether it needs some form of abstraction and then determine the best abstraction level for its needs.</p> <p>An interface should live on the consumer side in most cases. However, in particular contexts (for example, when we know\u2014not foresee\u2014that an abstraction will be helpful for consumers), we may want to have it on the producer side. If we do, we should strive to keep it as minimal as possible, increasing its reusability potential and making it more easily composable.</p> <p>Source code</p>"},{"location":"mistakes/#returning-interfaces-7","title":"Returning interfaces (#7)","text":"<p>TL;DR: To prevent being restricted in terms of flexibility, a function shouldn\u2019t return interfaces but concrete implementations in most cases. Conversely, a function should accept interfaces whenever possible.</p> <p>In most cases, we shouldn\u2019t return interfaces but concrete implementations. Otherwise, it can make our design more complex due to package dependencies and can restrict flexibility because all the clients would have to rely on the same abstraction. Again, the conclusion is similar to the previous sections: if we know (not foresee) that an abstraction will be helpful for clients, we can consider returning an interface. Otherwise, we shouldn\u2019t force abstractions; they should be discovered by clients. If a client needs to abstract an implementation for whatever reason, it can still do that on the client\u2019s side.</p>"},{"location":"mistakes/#any-says-nothing-8","title":"<code>any</code> says nothing (#8)","text":"<p>TL;DR: Only use <code>any</code> if you need to accept or return any possible type, such as <code>json.Marshal</code>. Otherwise, <code>any</code> doesn\u2019t provide meaningful information and can lead to compile-time issues by allowing a caller to call methods with any data type.</p> <p>The <code>any</code> type can be helpful if there is a genuine need for accepting or returning any possible type (for instance, when it comes to marshaling or formatting). In general, we should avoid overgeneralizing the code we write at all costs. Perhaps a little bit of duplicated code might occasionally be better if it improves other aspects such as code expressiveness.</p> <p>Source code</p>"},{"location":"mistakes/#being-confused-about-when-to-use-generics-9","title":"Being confused about when to use generics (#9)","text":"<p>TL;DR: Relying on generics and type parameters can prevent writing boilerplate code to factor out elements or behaviors. However, do not use type parameters prematurely, but only when you see a concrete need for them. Otherwise, they introduce unnecessary abstractions and complexity.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-aware-of-the-possible-problems-with-type-embedding-10","title":"Not being aware of the possible problems with type embedding (#10)","text":"<p>TL;DR: Using type embedding can also help avoid boilerplate code; however, ensure that doing so doesn\u2019t lead to visibility issues where some fields should have remained hidden.</p> <p>When creating a struct, Go offers the option to embed types. But this can sometimes lead to unexpected behaviors if we don\u2019t understand all the implications of type embedding. Throughout this section, we look at how to embed types, what these bring, and the possible issues.</p> <p>In Go, a struct field is called embedded if it\u2019s declared without a name. For example,</p> <pre><code>type Foo struct {\n    Bar // Embedded field\n}\n\ntype Bar struct {\n    Baz int\n}\n</code></pre> <p>In the <code>Foo</code> struct, the <code>Bar</code> type is declared without an associated name; hence, it\u2019s an embedded field.</p> <p>We use embedding to promote the fields and methods of an embedded type. Because Bar contains a Baz field, this field is promoted to <code>Foo</code>. Therefore, Baz becomes available from Foo.</p> <p>What can we say about type embedding? First, let\u2019s note that it\u2019s rarely a necessity, and it means that whatever the use case, we can probably solve it as well without type embedding. Type embedding is mainly used for convenience: in most cases, to promote behaviors.</p> <p>If we decide to use type embedding, we need to keep two main constraints in mind: * It shouldn\u2019t be used solely as some syntactic sugar to simplify accessing a field (such as <code>Foo.Baz()</code> instead of <code>Foo.Bar.Baz()</code>). If this is the only rationale, let\u2019s not embed the inner type and use a field instead. * It shouldn\u2019t promote data (fields) or a behavior (methods) we want to hide from the outside: for example, if it allows clients to access a locking behavior that should remain private to the struct.</p> <p>Using type embedding consciously by keeping these constraints in mind can help avoid boilerplate code with additional forwarding methods. However, let\u2019s make sure we don\u2019t do it solely for cosmetics and not promote elements that should remain hidden.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-the-functional-options-pattern-11","title":"Not using the functional options pattern (#11)","text":"<p>TL;DR: To handle options conveniently and in an API-friendly manner, use the functional options pattern.</p> <p>Although there are different implementations with minor variations, the main idea is as follows: * An unexported struct holds the configuration: options. * Each option is a function that returns the same type: <code>type Option func(options *options)</code> error. For example, <code>WithPort</code> accepts an <code>int</code> argument that represents the port and returns an <code>Option</code> type that represents how to update the <code>options</code> struct.</p> <p></p> <pre><code>type options struct {\n  port *int\n}\n\ntype Option func(options *options) error\n\nfunc WithPort(port int) Option {\n  return func(options *options) error {\n    if port &lt; 0 {\n    return errors.New(\"port should be positive\")\n  }\n  options.port = &amp;port\n  return nil\n  }\n}\n\nfunc NewServer(addr string, opts ...Option) ( *http.Server, error) { &lt;1&gt;\n  var options options &lt;2&gt;\n  for _, opt := range opts { &lt;3&gt;\n    err := opt(&amp;options) &lt;4&gt;\n    if err != nil {\n      return nil, err\n    }\n  }\n\n  // At this stage, the options struct is built and contains the config\n  // Therefore, we can implement our logic related to port configuration\n  var port int\n  if options.port == nil {\n    port = defaultHTTPPort\n  } else {\n      if *options.port == 0 {\n      port = randomPort()\n    } else {\n      port = *options.port\n    }\n  }\n\n  // ...\n}\n</code></pre> <p>The functional options pattern provides a handy and API-friendly way to handle options. Although the builder pattern can be a valid option, it has some minor downsides (having to pass a config struct that can be empty or a less handy way to handle error management) that tend to make the functional options pattern the idiomatic way to deal with these kind of problems in Go.</p> <p>Source code</p>"},{"location":"mistakes/#project-misorganization-project-structure-and-package-organization-12","title":"Project misorganization (project structure and package organization) (#12)","text":"<p>TL;DR: Following a layout such as project-layout can be a good way to start structuring Go projects, especially if you are looking for existing conventions to standardize a new project.</p> <p>Regarding the overall organization, there are different schools of thought. For example, should we organize our application by context or by layer? It depends on our preferences. We may favor grouping code per context (such as the customer context, the contract context, etc.), or we may favor following hexagonal architecture principles and group per technical layer. If the decision we make fits our use case, it cannot be a wrong decision, as long as we remain consistent with it.</p> <p>Regarding packages, there are multiple best practices that we should follow. First, we should avoid premature packaging because it might cause us to overcomplicate a project. Sometimes, it\u2019s better to use a simple organization and have our project evolve when we understand what it contains rather than forcing ourselves to make the perfect structure up front. Granularity is another essential thing to consider. We should avoid having dozens of nano packages containing only one or two files. If we do, it\u2019s because we have probably missed some logical connections across these packages, making our project harder for readers to understand. Conversely, we should also avoid huge packages that dilute the meaning of a package name.</p> <p>Package naming should also be considered with care. As we all know (as developers), naming is hard. To help clients understand a Go project, we should name our packages after what they provide, not what they contain. Also, naming should be meaningful. Therefore, a package name should be short, concise, expressive, and, by convention, a single lowercase word.</p> <p>Regarding what to export, the rule is pretty straightforward. We should minimize what should be exported as much as possible to reduce the coupling between packages and keep unnecessary exported elements hidden. If we are unsure whether to export an element or not, we should default to not exporting it. Later, if we discover that we need to export it, we can adjust our code. Let\u2019s also keep in mind some exceptions, such as making fields exported so that a struct can be unmarshaled with encoding/json.</p> <p>Organizing a project isn\u2019t straightforward, but following these rules should help make it easier to maintain. However, remember that consistency is also vital to ease maintainability. Therefore, let\u2019s make sure that we keep things as consistent as possible within a codebase.</p>"},{"location":"mistakes/#creating-utility-packages-13","title":"Creating utility packages (#13)","text":"<p>TL;DR: Naming is a critical piece of application design. Creating packages such as <code>common</code>, <code>util</code>, and <code>shared</code> doesn\u2019t bring much value for the reader. Refactor such packages into meaningful and specific package names.</p> <p>Also, bear in mind that naming a package after what it provides and not what it contains can be an efficient way to increase its expressiveness.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-package-name-collisions-14","title":"Ignoring package name collisions (#14)","text":"<p>TL;DR: To avoid naming collisions between variables and packages, leading to confusion or perhaps even bugs, use unique names for each one. If this isn\u2019t feasible, use an import alias to change the qualifier to differentiate the package name from the variable name, or think of a better name.</p> <p>Package collisions occur when a variable name collides with an existing package name, preventing the package from being reused. We should prevent variable name collisions to avoid ambiguity. If we face a collision, we should either find another meaningful name or use an import alias.</p>"},{"location":"mistakes/#missing-code-documentation-15","title":"Missing code documentation (#15)","text":"<p>TL;DR: To help clients and maintainers understand your code\u2019s purpose, document exported elements.</p> <p>Documentation is an important aspect of coding. It simplifies how clients can consume an API but can also help in maintaining a project. In Go, we should follow some rules to make our code idiomatic:</p> <p>First, every exported element must be documented. Whether it is a structure, an interface, a function, or something else, if it\u2019s exported, it must be documented. The convention is to add comments, starting with the name of the exported element.</p> <p>As a convention, each comment should be a complete sentence that ends with punctuation. Also bear in mind that when we document a function (or a method), we should highlight what the function intends to do, not how it does it; this belongs to the core of a function and comments, not documentation. Furthermore, the documentation should ideally provide enough information that the consumer does not have to look at our code to understand how to use an exported element.</p> <p>When it comes to documenting a variable or a constant, we might be interested in conveying two aspects: its purpose and its content. The former should live as code documentation to be useful for external clients. The latter, though, shouldn\u2019t necessarily be public.</p> <p>To help clients and maintainers understand a package\u2019s scope, we should also document each package. The convention is to start the comment with <code>// Package</code> followed by the package name. The first line of a package comment should be concise. That\u2019s because it will appear in the package. Then, we can provide all the information we need in the following lines.</p> <p>Documenting our code shouldn\u2019t be a constraint. We should take the opportunity to make sure it helps clients and maintainers to understand the purpose of our code.</p>"},{"location":"mistakes/#not-using-linters-16","title":"Not using linters (#16)","text":"<p>TL;DR: To improve code quality and consistency, use linters and formatters.</p> <p>A linter is an automatic tool to analyze code and catch errors. The scope of this section isn\u2019t to give an exhaustive list of the existing linters; otherwise, it will become deprecated pretty quickly. But we should understand and remember why linters are essential for most Go projects.</p> <p>However, if you\u2019re not a regular user of linters, here is a list that you may want to use daily: * https://golang.org/cmd/vet/\u2014A standard Go analyzer * https://github.com/kisielk/errcheck\u2014An error checker * https://github.com/fzipp/gocyclo\u2014A cyclomatic complexity analyzer * https://github.com/jgautheron/goconst\u2014A repeated string constants analyzer * Besides linters, we should also use code formatters to fix code style. Here is a list of some code formatters for you to try: * https://golang.org/cmd/gofmt/\u2014A standard Go code formatter * https://godoc.org/golang.org/x/tools/cmd/goimports\u2014A standard Go imports formatter * Meanwhile, we should also look at golangci-lint (https://github.com/golangci/ golangci-lint). It\u2019s a linting tool that provides a facade on top of many useful linters and formatters. Also, it allows running the linters in parallel to improve analysis speed, which is quite handy.</p> <p>Linters and formatters are a powerful way to improve the quality and consistency of our codebase. Let\u2019s take the time to understand which one we should use and make sure we automate their execution (such as a CI or Git precommit hook).</p>"},{"location":"mistakes/#data-types","title":"Data Types","text":""},{"location":"mistakes/#creating-confusion-with-octal-literals-17","title":"Creating confusion with octal literals (#17)","text":"<p>TL;DR: When reading existing code, bear in mind that integer literals starting with 0 are octal numbers. Also, to improve readability, make octal integers explicit by prefixing them with <code>0o</code>.</p> <p>Octal numbers start with a 0 (e.g., <code>010</code> is equal to 8 in base 10). To improve readability and avoid potential mistakes for future code readers, we should make octal numbers explicit using the <code>0o</code> prefix (e.g., <code>0o10</code>).</p> <p>We should also note the other integer literal representations: * Binary\u2014Uses a <code>0b</code> or <code>0B</code> prefix (for example, <code>0b100</code> is equal to 4 in base 10) * Hexadecimal\u2014Uses an <code>0x</code> or <code>0X</code> prefix (for example, <code>0xF</code> is equal to 15 in base 10) * Imaginary\u2014Uses an <code>i</code> suffix (for example, <code>3i</code>)</p> <p>We can also use an underscore character (_) as a separator for readability. For example, we can write 1 billion this way: <code>1_000_000_000</code>. We can also use the under- score character with other representations (for example, <code>0b00_00_01</code>).</p> <p>Source code</p>"},{"location":"mistakes/#neglecting-integer-overflows-18","title":"Neglecting integer overflows (#18)","text":"<p>TL;DR: Because integer overflows and underflows are handled silently in Go, you can implement your own functions to catch them.</p> <p>In Go, an integer overflow that can be detected at compile time generates a compila- tion error. For example,</p> <pre><code>var counter int32 = math.MaxInt32 + 1\n</code></pre> <pre><code>constant 2147483648 overflows int32\n</code></pre> <p>However, at run time, an integer overflow or underflow is silent; this does not lead to an application panic. It is essential to keep this behavior in mind, because it can lead to sneaky bugs (for example, an integer increment or addition of positive integers that leads to a negative result).</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-floating-points-19","title":"Not understanding floating-points (#19)","text":"<p>TL;DR: Making floating-point comparisons within a given delta can ensure that your code is portable. When performing addition or subtraction, group the operations with a similar order of magnitude to favor accuracy. Also, perform multiplication and division before addition and subtraction.</p> <p>In Go, there are two floating-point types (if we omit imaginary numbers): float32 and float64. The concept of a floating point was invented to solve the major problem with integers: their inability to represent fractional values. To avoid bad surprises, we need to know that floating-point arithmetic is an approximation of real arithmetic.</p> <p>For that, we\u2019ll look at a multiplication example:</p> <pre><code>var n float32 = 1.0001\nfmt.Println(n * n)\n</code></pre> <p>We may expect this code to print the result of 1.0001 * 1.0001 = 1.00020001, right? However, running it on most x86 processors prints 1.0002, instead.</p> <p>Because Go\u2019s <code>float32</code> and <code>float64</code> types are approximations, we have to bear a few rules in mind: * When comparing two floating-point numbers, check that their difference is within an acceptable range. * When performing additions or subtractions, group operations with a similar order of magnitude for better accuracy. * To favor accuracy, if a sequence of operations requires addition, subtraction, multiplication, or division, perform the multiplication and division operations first.</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-slice-length-and-capacity-20","title":"Not understanding slice length and capacity (#20)","text":"<p>TL;DR: Understanding the difference between slice length and capacity should be part of a Go developer\u2019s core knowledge. The slice length is the number of available elements in the slice, whereas the slice capacity is the number of elements in the backing array.</p> <p>Source code</p>"},{"location":"mistakes/#inefficient-slice-initialization-21","title":"Inefficient slice initialization (#21)","text":"<p>TL;DR: When creating a slice, initialize it with a given length or capacity if its length is already known. This reduces the number of allocations and improves performance.</p> <p>While initializing a slice using <code>make</code>, we can provide a length and an optional capacity. Forgetting to pass an appropriate value for both of these parameters when it makes sense is a widespread mistake. Indeed, it can lead to multiple copies and additional effort for the GC to clean the temporary backing arrays. Performance-wise, there\u2019s no good reason not to give the Go runtime a helping hand.</p> <p>Our options are to allocate a slice with either a given capacity or a given length. Of these two solutions, we have seen that the second tends to be slightly faster. But using a given capacity and append can be easier to implement and read in some contexts.</p> <p>Source code</p>"},{"location":"mistakes/#being-confused-about-nil-vs-empty-slice-22","title":"Being confused about nil vs. empty slice (#22)","text":"<p>TL;DR: To prevent common confusions such as when using the <code>encoding/json</code> or the <code>reflect</code> package, you need to understand the difference between nil and empty slices. Both are zero-length, zero-capacity slices, but only a nil slice doesn\u2019t require allocation.</p> <p>In Go, there is a distinction between nil and empty slices. A nil slice is equals to <code>nil</code>, whereas an empty slice has a length of zero. A nil slice is empty, but an empty slice isn\u2019t necessarily <code>nil</code>. Meanwhile, a nil slice doesn\u2019t require any allocation. We have seen throughout this section how to initialize a slice depending on the con- text by using</p> <ul> <li><code>var s []string</code> if we aren\u2019t sure about the final length and the slice can be empty</li> <li><code>[]string(nil)</code> as syntactic sugar to create a nil and empty slice</li> <li><code>make([]string, length)</code> if the future length is known</li> </ul> <p>The last option, <code>[]string{}</code>, should be avoided if we initialize the slice without ele- ments. Finally, let\u2019s check whether the libraries we use make the distinctions between nil and empty slices to prevent unexpected behaviors.</p> <p>Source code</p>"},{"location":"mistakes/#not-properly-checking-if-a-slice-is-empty-23","title":"Not properly checking if a slice is empty (#23)","text":"<p>TL;DR: To check if a slice doesn\u2019t contain any element, check its length. This check works regardless of whether the slice is <code>nil</code> or empty. The same goes for maps. To design unambiguous APIs, you shouldn\u2019t distinguish between nil and empty slices.</p> <p>To determine whether a slice has elements, we can either do it by checking if the slice is nil or if its length is equal to 0. Checking the length is the best option to follow as it will cover both if the slice is empty or is the slice is nil.</p> <p>Meanwhile, when designing interfaces, we should avoid distinguishing nil and empty slices, which leads to subtle programming errors. When returning slices, it should make neither a seman- tic nor a technical difference if we return a nil or empty slice. Both should mean the same thing for the callers. This principle is the same with maps. To check if a map is empty, check its length, not whether it\u2019s nil.</p> <p>Source code</p>"},{"location":"mistakes/#not-making-slice-copies-correctly-24","title":"Not making slice copies correctly (#24)","text":"<p>TL;DR: To copy one slice to another using the <code>copy</code> built-in function, remember that the number of copied elements corresponds to the minimum between the two slice\u2019s lengths.</p> <p>Copying elements from one slice to another is a reasonably frequent operation. When using copy, we must recall that the number of elements copied to the destina- tion corresponds to the minimum between the two slices\u2019 lengths. Also bear in mind that other alternatives exist to copy a slice, so we shouldn\u2019t be surprised if we find them in a codebase.</p> <p>Source code</p>"},{"location":"mistakes/#unexpected-side-effects-using-slice-append-25","title":"Unexpected side effects using slice append (#25)","text":"<p>TL;DR: Using copy or the full slice expression is a way to prevent <code>append</code> from creating conflicts if two different functions use slices backed by the same array. However, only a slice copy prevents memory leaks if you want to shrink a large slice.</p> <p>When using slicing, we must remember that we can face a situation leading to unintended side effects. If the resulting slice has a length smaller than its capacity, append can mutate the original slice. If we want to restrict the range of possible side effects, we can use either a slice copy or the full slice expression, which prevents us from doing a copy.</p> <p>[!NOTE] <code>s[low:high:max]</code> (full slice expression): This statement creates a slice similar to the one created with <code>s[low:high]</code>, except that the resulting slice\u2019s capacity is equal to <code>max - low</code>.</p> <p>Source code</p>"},{"location":"mistakes/#slice-and-memory-leaks-26","title":"Slice and memory leaks (#26)","text":"<p>TL;DR: Working with a slice of pointers or structs with pointer fields, you can avoid memory leaks by marking as nil the elements excluded by a slicing operation.</p>"},{"location":"mistakes/#leaking-capacity","title":"Leaking capacity","text":"<p>Remember that slicing a large slice or array can lead to potential high memory consumption. The remaining space won\u2019t be reclaimed by the GC, and we can keep a large backing array despite using only a few elements. Using a slice copy is the solution to prevent such a case.</p> <p>Source code</p>"},{"location":"mistakes/#slice-and-pointers","title":"Slice and pointers","text":"<p>When we use the slicing operation with pointers or structs with pointer fields, we need to know that the GC won\u2019t reclaim these elements. In that case, the two options are to either perform a copy or explicitly mark the remaining elements or their fields to <code>nil</code>.</p> <p>Source code</p>"},{"location":"mistakes/#inefficient-map-initialization-27","title":"Inefficient map initialization (#27)","text":"<p>TL;DR: When creating a map, initialize it with a given length if its length is already known. This reduces the number of allocations and improves performance.</p> <p>A map provides an unordered collection of key-value pairs in which all the keys are dis- tinct. In Go, a map is based on the hash table data structure. Internally, a hash table is an array of buckets, and each bucket is a pointer to an array of key-value pairs.</p> <p>If we know up front the number of elements a map will contain, we should create it by providing an initial size. Doing this avoids potential map growth, which is quite heavy computation-wise because it requires reallocating enough space and rebalancing all the elements.</p> <p>Source code</p>"},{"location":"mistakes/#map-and-memory-leaks-28","title":"Map and memory leaks (#28)","text":"<p>TL;DR: A map can always grow in memory, but it never shrinks. Hence, if it leads to some memory issues, you can try different options, such as forcing Go to recreate the map or using pointers.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-values-incorrectly-29","title":"Comparing values incorrectly (#29)","text":"<p>TL;DR: To compare types in Go, you can use the == and != operators if two types are comparable: Booleans, numerals, strings, pointers, channels, and structs are composed entirely of comparable types. Otherwise, you can either use <code>reflect.DeepEqual</code> and pay the price of reflection or use custom implementations and libraries.</p> <p>It\u2019s essential to understand how to use <code>==</code> and <code>!=</code> to make comparisons effectively. We can use these operators on operands that are comparable: * Booleans\u2014Compare whether two Booleans are equal. * Numerics (int, float, and complex types)\u2014Compare whether two numerics are equal. * Strings\u2014Compare whether two strings are equal. * Channels\u2014Compare whether two channels were created by the same call to make or if both are nil. * Interfaces\u2014Compare whether two interfaces have identical dynamic types and equal dynamic values or if both are nil. * Pointers\u2014Compare whether two pointers point to the same value in memory or if both are nil. * _Structs and arrays)\u2014Compare whether they are composed of similar types.</p> <p>[!NOTE] We can also use the <code>?</code>, <code>&gt;=</code>, <code>&lt;</code>, and <code>&gt;</code> operators with numeric types to compare values and with strings to compare their lexical order.</p> <p>If operands are not comparable (e.g., slices and maps), we have to use other options such as reflection. Reflection is a form of metaprogramming, and it refers to the ability of an applica- tion to introspect and modify its structure and behavior. For example, in Go, we can use <code>reflect.DeepEqual</code>. This function reports whether two elements are deeply equal by recursively traversing two values. The elements it accepts are basic types plus arrays, structs, slices, maps, pointers, interfaces, and functions. Yet, the main catch is the performance penalty.</p> <p>If performance is crucial at run time, implementing our custom method might be the best solution. One additional note: we must remember that the standard library has some exist- ing comparison methods. For example, we can use the optimized <code>bytes.Compare</code> function to compare two slices of bytes. Before implementing a custom method, we need to make sure we don\u2019t reinvent the wheel.</p> <p>Source code</p>"},{"location":"mistakes/#control-structures","title":"Control Structures","text":""},{"location":"mistakes/#ignoring-that-elements-are-copied-in-range-loops-30","title":"Ignoring that elements are copied in <code>range</code> loops (#30)","text":"<p>TL;DR: The value element in a <code>range</code> loop is a copy. Therefore, to mutate a struct, for example, access it via its index or via a classic <code>for</code> loop (unless the element or the field you want to modify is a pointer).</p> <p>A range loop allows iterating over different data structures: * String * Array * Pointer to an array * Slice * Map * Receiving channel</p> <p>Compared to a classic for <code>loop</code>, a <code>range</code> loop is a convenient way to iterate over all the elements of one of these data structures, thanks to its concise syntax.</p> <p>Yet, we should remember that the value element in a range loop is a copy. Therefore, if the value is a struct we need to mutate, we will only update the copy, not the element itself, unless the value or field we modify is a pointer. The favored options are to access the element via the index using a range loop or a classic for loop.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-arguments-are-evaluated-in-range-loops-channels-and-arrays-31","title":"Ignoring how arguments are evaluated in <code>range</code> loops (channels and arrays) (#31)","text":"<p>TL;DR: Understanding that the expression passed to the <code>range</code> operator is evaluated only once before the beginning of the loop can help you avoid common mistakes such as inefficient assignment in channel or slice iteration.</p> <p>The range loop evaluates the provided expression only once, before the beginning of the loop, by doing a copy (regardless of the type). We should remember this behavior to avoid common mistakes that might, for example, lead us to access the wrong element. For example:</p> <pre><code>a := [3]int{0, 1, 2}\nfor i, v := range a {\n    a[2] = 10\n    if i == 2 {\n        fmt.Println(v)\n    }\n}\n</code></pre> <p>This code updates the last index to 10. However, if we run this code, it does not print 10; it prints 2.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-the-impacts-of-using-pointer-elements-in-range-loops-32","title":"Ignoring the impacts of using pointer elements in <code>range</code> loops (#32)","text":"<p>TL;DR: Using a local variable or accessing an element using an index, you can prevent mistakes while copying pointers inside a loop.</p> <p>When iterating over a data structure using a <code>range</code> loop, we must recall that all the values are assigned to a unique variable with a single unique address. Therefore, if we store a pointer referencing this variable during each iteration, we will end up in a situ- ation where we store the same pointer referencing the same element: the latest one. We can overcome this issue by forcing the creation of a local variable in the loop\u2019s scope or creating a pointer referencing a slice element via its index. Both solutions are fine.</p> <p>Source code</p>"},{"location":"mistakes/#making-wrong-assumptions-during-map-iterations-ordering-and-map-insert-during-iteration-33","title":"Making wrong assumptions during map iterations (ordering and map insert during iteration) (#33)","text":"<p>TL;DR: To ensure predictable outputs when using maps, remember that a map data structure: * Doesn\u2019t order the data by keys * Doesn\u2019t preserve the insertion order * Doesn\u2019t have a deterministic iteration order * Doesn\u2019t guarantee that an element added during an iteration will be produced during this iteration</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-the-break-statement-works-34","title":"Ignoring how the <code>break</code> statement works (#34)","text":"<p>TL;DR: Using <code>break</code> or <code>continue</code> with a label enforces breaking a specific statement. This can be helpful with <code>switch</code> or <code>select</code> statements inside loops.</p> <p>A break statement is commonly used to terminate the execution of a loop. When loops are used in conjunction with switch or select, developers frequently make the mistake of breaking the wrong statement. For example:</p> <pre><code>for i := 0; i &lt; 5; i++ {\n    fmt.Printf(\"%d \", i)\n\n    switch i {\n    default:\n    case 2:\n        break\n    }\n}\n</code></pre> <p>The break statement doesn\u2019t terminate the <code>for</code> loop: it terminates the <code>switch</code> statement, instead. Hence, instead of iterating from 0 to 2, this code iterates from 0 to 4: <code>0 1 2 3 4</code>.</p> <p>One essential rule to keep in mind is that a <code>break</code> statement terminates the execu- tion of the innermost <code>for</code>, <code>switch</code>, or <code>select</code> statement. In the previous example, it terminates the <code>switch</code> statement.</p> <p>To break the loop instead of the <code>switch</code> statement, the most idiomatic way is to use a label:</p> <pre><code>loop:\n    for i := 0; i &lt; 5; i++ {\n        fmt.Printf(\"%d \", i)\n\n        switch i {\n        default:\n        case 2:\n            break loop\n        }\n    }\n</code></pre> <p>Here, we associate the <code>loop</code> label with the <code>for</code> loop. Then, because we provide the <code>loop</code> label to the <code>break</code> statement, it breaks the loop, not the switch. Therefore, this new version will print <code>0 1 2</code>, as we expected.</p> <p>Source code</p>"},{"location":"mistakes/#using-defer-inside-a-loop-35","title":"Using <code>defer</code> inside a loop (#35)","text":"<p>TL;DR: Extracting loop logic inside a function leads to executing a <code>defer</code> statement at the end of each iteration.</p> <p>The <code>defer</code> statement delays a call\u2019s execution until the surrounding function returns. It\u2019s mainly used to reduce boilerplate code. For example, if a resource has to be closed eventually, we can use <code>defer</code> to avoid repeating the closure calls before every single <code>return</code>.</p> <p>One common mistake with <code>defer</code> is to forget that it schedules a function call when the surrounding function returns. For example:</p> <pre><code>func readFiles(ch &lt;-chan string) error {\n    for path := range ch {\n        file, err := os.Open(path)\n        if err != nil {\n            return err\n        }\n\n        defer file.Close()\n\n        // Do something with file\n    }\n    return nil\n}\n</code></pre> <p>The <code>defer</code> calls are executed not during each loop iteration but when the <code>readFiles</code> function returns. If <code>readFiles</code> doesn\u2019t return, the file descriptors will be kept open forever, causing leaks.</p> <p>One common option to fix this problem is to create a surrounding function after <code>defer</code>, called during each iteration:</p> <pre><code>func readFiles(ch &lt;-chan string) error {\n    for path := range ch {\n        if err := readFile(path); err != nil {\n            return err\n        }\n    }\n    return nil\n}\n\nfunc readFile(path string) error {\n    file, err := os.Open(path)\n    if err != nil {\n        return err\n    }\n\n    defer file.Close()\n\n    // Do something with file\n    return nil\n}\n</code></pre> <p>Another solution is to make the <code>readFile</code> function a closure but intrinsically, this remains the same solution: adding another surrounding function to execute the <code>defer</code> calls during each iteration.</p> <p>Source code</p>"},{"location":"mistakes/#strings","title":"Strings","text":""},{"location":"mistakes/#not-understanding-the-concept-of-rune-36","title":"Not understanding the concept of rune (#36)","text":"<p>TL;DR: Understanding that a rune corresponds to the concept of a Unicode code point and that it can be composed of multiple bytes should be part of the Go developer\u2019s core knowledge to work accurately with strings.</p> <p>As runes are everywhere in Go, it's important to understand the following:</p> <ul> <li>A charset is a set of characters, whereas an encoding describes how to translate a charset into binary.</li> <li>In Go, a string references an immutable slice of arbitrary bytes.</li> <li>Go source code is encoded using UTF-8. Hence, all string literals are UTF-8 strings. But because a string can contain arbitrary bytes, if it\u2019s obtained from somewhere else (not the source code), it isn\u2019t guaranteed to be based on the UTF-8 encoding.</li> <li>A <code>rune</code> corresponds to the concept of a Unicode code point, meaning an item represented by a single value.</li> <li>Using UTF-8, a Unicode code point can be encoded into 1 to 4 bytes.</li> <li>Using <code>len()</code> on a string in Go returns the number of bytes, not the number of runes.</li> </ul> <p>Source code</p>"},{"location":"mistakes/#inaccurate-string-iteration-37","title":"Inaccurate string iteration (#37)","text":"<p>TL;DR: Iterating on a string with the <code>range</code> operator iterates on the runes with the index corresponding to the starting index of the rune\u2019s byte sequence. To access a specific rune index (such as the third rune), convert the string into a <code>[]rune</code>.</p> <p>Iterating on a string is a common operation for developers. Perhaps we want to per- form an operation for each rune in the string or implement a custom function to search for a specific substring. In both cases, we have to iterate on the different runes of a string. But it\u2019s easy to get confused about how iteration works.</p> <p>For example, consider the following example:</p> <pre><code>s := \"h\u00eallo\"\nfor i := range s {\n    fmt.Printf(\"position %d: %c\\n\", i, s[i])\n}\nfmt.Printf(\"len=%d\\n\", len(s))\n</code></pre> <pre><code>position 0: h\nposition 1: \u00c3\nposition 3: l\nposition 4: l\nposition 5: o\nlen=6\n</code></pre> <p>Let's highlight three points that might be confusing:</p> <ul> <li>The second rune is \u00c3 in the output instead of \u00ea.</li> <li>We jumped from position 1 to position 3: what is at position 2?</li> <li>len returns a count of 6, whereas s contains only 5 runes.</li> </ul> <p>Let\u2019s start with the last observation. We already mentioned that len returns the num- ber of bytes in a string, not the number of runes. Because we assigned a string literal to <code>s</code>, <code>s</code> is a UTF-8 string. Meanwhile, the special character \"\u00ea\" isn\u2019t encoded in a single byte; it requires 2 bytes. Therefore, calling <code>len(s)</code> returns 6.</p> <p>Meanwhile, in the previous example, we have to understand that we don't iterate over each rune; instead, we iterate over each starting index of a rune:</p> <p></p> <p>Printing <code>s[i]</code> doesn\u2019t print the ith rune; it prints the UTF-8 representation of the byte at index <code>i</code>. Hence, we printed \"h\u00c3llo\" instead of \"h\u00eallo\".</p> <p>If we want to print all the different runes, we can either use the value element of the <code>range</code> operator:</p> <pre><code>s := \"h\u00eallo\"\nfor i, r := range s {\n    fmt.Printf(\"position %d: %c\\n\", i, r)\n}\n</code></pre> <p>Or, we can convert the string into a slice of runes and iterate over it:</p> <pre><code>s := \"h\u00eallo\"\nrunes := []rune(s)\nfor i, r := range runes {\n    fmt.Printf(\"position %d: %c\\n\", i, r)\n}\n</code></pre> <p>Note that this solution introduces a run-time overhead compared to the previous one. Indeed, converting a string into a slice of runes requires allocating an additional slice and converting the bytes into runes: an O(n) time complexity with n the number of bytes in the string. Therefore, if we want to iterate over all the runes, we should use the first solution.</p> <p>However, if we want to access the ith rune of a string with the first option, we don\u2019t have access to the rune index; rather, we know the starting index of a rune in the byte sequence.</p> <pre><code>s := \"h\u00eallo\"\nr := []rune(s)[4]\nfmt.Printf(\"%c\\n\", r) // o\n</code></pre> <p>Source code</p>"},{"location":"mistakes/#misusing-trim-functions-38","title":"Misusing trim functions (#38)","text":"<p>TL;DR: <code>strings.TrimRight</code>/<code>strings.TrimLeft</code> removes all the trailing/leading runes contained in a given set, whereas <code>strings.TrimSuffix</code>/<code>strings.TrimPrefix</code> returns a string without a provided suffix/prefix.</p> <p>For example:</p> <pre><code>fmt.Println(strings.TrimRight(\"123oxo\", \"xo\"))\n</code></pre> <p>The example prints 123:</p> <p></p> <p>Conversely, <code>strings.TrimLeft</code> removes all the leading runes contained in a set.</p> <p>On the other side, <code>strings.TrimSuffix</code> / <code>strings.TrimPrefix</code> returns a string without the provided trailing suffix / prefix.</p> <p>Source code</p>"},{"location":"mistakes/#under-optimized-strings-concatenation-39","title":"Under-optimized strings concatenation (#39)","text":"<p>TL;DR: Concatenating a list of strings should be done with <code>strings.Builder</code> to prevent allocating a new string during each iteration.</p> <p>Let\u2019s consider a <code>concat</code> function that concatenates all the string elements of a slice using the <code>+=</code> operator:</p> <pre><code>func concat(values []string) string {\n    s := \"\"\n    for _, value := range values {\n        s += value\n    }\n    return s\n}\n</code></pre> <p>During each iteration, the <code>+=</code> operator concatenates <code>s</code> with the value string. At first sight, this function may not look wrong. But with this implementation, we forget one of the core characteristics of a string: its immutability. Therefore, each iteration doesn\u2019t update <code>s</code>; it reallocates a new string in memory, which significantly impacts the performance of this function.</p> <p>Fortunately, there is a solution to deal with this problem, using <code>strings.Builder</code>:</p> <pre><code>func concat(values []string) string {\n    sb := strings.Builder{}\n    for _, value := range values {\n        _, _ = sb.WriteString(value)\n    }\n    return sb.String()\n}\n</code></pre> <p>During each iteration, we constructed the resulting string by calling the <code>WriteString</code> method that appends the content of value to its internal buffer, hence minimizing memory copying.</p> <p>[!NOTE] <code>WriteString</code> returns an error as the second output, but we purposely ignore it. Indeed, this method will never return a non-nil error. So what\u2019s the purpose of this method returning an error as part of its signature? <code>strings.Builder</code> imple- ments the <code>io.StringWriter</code> interface, which contains a single method: <code>WriteString(s string) (n int, err error)</code>. Hence, to comply with this interface, <code>WriteString</code> must return an error.</p> <p>Internally, <code>strings.Builder</code> holds a byte slice. Each call to <code>WriteString</code> results in a call to append on this slice. There are two impacts. First, this struct shouldn\u2019t be used concurrently, as the calls to <code>append</code> would lead to race conditions. The second impact is something that we saw in mistake #21, \"Inefficient slice initialization\": if the future length of a slice is already known, we should preallocate it. For that purpose, <code>strings.Builder</code> exposes a method <code>Grow(n int)</code> to guarantee space for another <code>n</code> bytes:</p> <pre><code>func concat(values []string) string {\n    total := 0\n    for i := 0; i &lt; len(values); i++ {\n        total += len(values[i])\n    }\n\n    sb := strings.Builder{}\n    sb.Grow(total) (2)\n    for _, value := range values {\n        _, _ = sb.WriteString(value)\n    }\n    return sb.String()\n}\n</code></pre> <p>Let\u2019s run a benchmark to compare the three versions (v1 using <code>+=</code>; v2 using <code>strings.Builder{}</code> without preallocation; and v3 using <code>strings.Builder{}</code> with pre- allocation). The input slice contains 1,000 strings, and each string contains 1,000 bytes:</p> <pre><code>BenchmarkConcatV1-4             16      72291485 ns/op\nBenchmarkConcatV2-4           1188        878962 ns/op\nBenchmarkConcatV3-4           5922        190340 ns/op\n</code></pre> <p>As we can see, the latest version is by far the most efficient: 99% faster than v1 and 78% faster than v2.</p> <p><code>strings.Builder</code> is the recommended solution to concatenate a list of strings. Usually, this solution should be used within a loop. Indeed, if we just have to concate- nate a few strings (such as a name and a surname), using <code>strings.Builder</code> is not rec- ommended as doing so will make the code a bit less readable than using the <code>+=</code> operator or <code>fmt.Sprintf</code>.</p> <p>Source code</p>"},{"location":"mistakes/#useless-string-conversions-40","title":"Useless string conversions (#40)","text":"<p>TL;DR: Remembering that the <code>bytes</code> package offers the same operations as the <code>strings</code> package can help avoid extra byte/string conversions.</p> <p>When choosing to work with a string or a <code>[]byte</code>, most programmers tend to favor strings for convenience. But most I/O is actually done with <code>[]byte</code>. For example, <code>io.Reader</code>, <code>io.Writer</code>, and <code>io.ReadAll</code> work with <code>[]byte</code>, not strings.</p> <p>When we\u2019re wondering whether we should work with strings or <code>[]byte</code>, let\u2019s recall that working with <code>[]byte</code> isn\u2019t necessarily less convenient. Indeed, all the exported functions of the strings package also have alternatives in the <code>bytes</code> package: <code>Split</code>, <code>Count</code>, <code>Contains</code>, <code>Index</code>, and so on. Hence, whether we\u2019re doing I/O or not, we should first check whether we could implement a whole workflow using bytes instead of strings and avoid the price of additional conversions.</p> <p>Source code</p>"},{"location":"mistakes/#substring-and-memory-leaks-41","title":"Substring and memory leaks (#41)","text":"<p>TL;DR: Using copies instead of substrings can prevent memory leaks, as the string returned by a substring operation will be backed by the same byte array.</p> <p>In mistake #26, \u201cSlices and memory leaks,\u201d we saw how slicing a slice or array may lead to memory leak situations. This principle also applies to string and substring opera- tions.</p> <p>We need to keep two things in mind while using the substring operation in Go. First, the interval provided is based on the number of bytes, not the number of runes. Second, a substring operation may lead to a memory leak as the resulting substring will share the same backing array as the initial string. The solutions to prevent this case from happening are to perform a string copy manually or to use <code>strings.Clone</code> from Go 1.18.</p> <p>Source code</p>"},{"location":"mistakes/#functions-and-methods","title":"Functions and Methods","text":""},{"location":"mistakes/#not-knowing-which-type-of-receiver-to-use-42","title":"Not knowing which type of receiver to use (#42)","text":"<p>TL;DR: The decision whether to use a value or a pointer receiver should be made based on factors such as the type, whether it has to be mutated, whether it contains a field that can\u2019t be copied, and how large the object is. When in doubt, use a pointer receiver.</p> <p>Choosing between value and pointer receivers isn\u2019t always straightforward. Let\u2019s dis- cuss some of the conditions to help us choose.</p> <p>A receiver must be a pointer</p> <ul> <li>If the method needs to mutate the receiver. This rule is also valid if the receiver is a slice and a method needs to append elements:</li> </ul> <p>```cgo   type slice []int</p> <p>func (s slice) add(element int) {             s = append(*s, element)   }   ```</p> <ul> <li>If the method receiver contains a field that cannot be copied: for example, a type part of the sync package (see #74, \u201cCopying a sync type\u201d).</li> </ul> <p>A receiver should be a pointer</p> <ul> <li>If the receiver is a large object. Using a pointer can make the call more effi- cient, as doing so prevents making an extensive copy. When in doubt about how large is large, benchmarking can be the solution; it\u2019s pretty much impossible to state a specific size, because it depends on many factors.</li> </ul> <p>A receiver must be a value</p> <ul> <li>If we have to enforce a receiver\u2019s immutability.</li> <li>If the receiver is a map, function, or channel. Otherwise, a compilation error   occurs.</li> </ul> <p>A receiver should be a value</p> <ul> <li>If the receiver is a slice that doesn\u2019t have to be mutated.</li> <li>If the receiver is a small array or struct that is naturally a value type without mutable fields, such as <code>time.Time</code>.</li> <li>If the receiver is a basic type such as <code>int</code>, <code>float64</code>, or <code>string</code>.</li> </ul> <p>Of course, it\u2019s impossible to be exhaustive, as there will always be edge cases, but this section\u2019s goal was to provide guidance to cover most cases. By default, we can choose to go with a value receiver unless there\u2019s a good reason not to do so. In doubt, we should use a pointer receiver.</p> <p>Source code</p>"},{"location":"mistakes/#never-using-named-result-parameters-43","title":"Never using named result parameters (#43)","text":"<p>TL;DR: Using named result parameters can be an efficient way to improve the readability of a function/method, especially if multiple result parameters have the same type. In some cases, this approach can also be convenient because named result parameters are initialized to their zero value. But be cautious about potential side effects.</p> <p>When we return parameters in a function or a method, we can attach names to these parameters and use them as regular variables. When a result parameter is named, it\u2019s initialized to its zero value when the function/method begins. With named result parameters, we can also call a naked return statement (without argu- ments). In that case, the current values of the result parameters are used as the returned values.</p> <p>Here\u2019s an example that uses a named result parameter <code>b</code>:</p> <pre><code>func f(a int) (b int) {\n    b = a\n    return\n}\n</code></pre> <p>In this example, we attach a name to the result parameter: <code>b</code>. When we call return without arguments, it returns the current value of <code>b</code>.</p> <p>In some cases, named result parameters can also increase readability: for example, if two parameters have the same type. In other cases, they can also be used for convenience. Therefore, we should use named result parameters sparingly when there\u2019s a clear benefit.</p> <p>Source code</p>"},{"location":"mistakes/#unintended-side-effects-with-named-result-parameters-44","title":"Unintended side effects with named result parameters (#44)","text":"<p>TL;DR: See #43.</p> <p>We mentioned why named result parameters can be useful in some situations. But as these result parameters are initialized to their zero value, using them can sometimes lead to subtle bugs if we\u2019re not careful enough. For example, can you spot what\u2019s wrong with this code?</p> <pre><code>func (l loc) getCoordinates(ctx context.Context, address string) (\n    lat, lng float32, err error) {\n    isValid := l.validateAddress(address) (1)\n    if !isValid {\n        return 0, 0, errors.New(\"invalid address\")\n    }\n\n    if ctx.Err() != nil { (2)\n        return 0, 0, err\n    }\n\n    // Get and return coordinates\n}\n</code></pre> <p>The error might not be obvious at first glance. Here, the error returned in the <code>if ctx.Err() != nil</code> scope is <code>err</code>. But we haven\u2019t assigned any value to the <code>err</code> variable. It\u2019s still assigned to the zero value of an <code>error</code> type: <code>nil</code>. Hence, this code will always return a nil error.</p> <p>When using named result parameters, we must recall that each parameter is initial- ized to its zero value. As we have seen in this section, this can lead to subtle bugs that aren\u2019t always straightforward to spot while reading code. Therefore, let\u2019s remain cau- tious when using named result parameters, to avoid potential side effects.</p> <p>Source code</p>"},{"location":"mistakes/#returning-a-nil-receiver-45","title":"Returning a nil receiver (#45)","text":"<p>TL;DR: When returning an interface, be cautious about returning not a nil pointer but an explicit nil value. Otherwise, unintended consequences may result because the caller will receive a non-nil value.</p> <p>Source code</p>"},{"location":"mistakes/#using-a-filename-as-a-function-input-46","title":"Using a filename as a function input (#46)","text":"<p>TL;DR: Designing functions to receive <code>io.Reader</code> types instead of filenames improves the reusability of a function and makes testing easier.</p> <p>Accepting a filename as a function input to read from a file should, in most cases, be considered a code smell (except in specific functions such as <code>os.Open</code>). Indeed, it makes unit tests more complex because we may have to create multiple files. It also reduces the reusability of a function (although not all functions are meant to be reused). Using the <code>io.Reader</code> interface abstracts the data source. Regardless of whether the input is a file, a string, an HTTP request, or a gRPC request, the imple- mentation can be reused and easily tested.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-how-defer-arguments-and-receivers-are-evaluated-argument-evaluation-pointer-and-value-receivers-47","title":"Ignoring how <code>defer</code> arguments and receivers are evaluated (argument evaluation, pointer, and value receivers) (#47)","text":"<p>TL;DR: Passing a pointer to a <code>defer</code> function and wrapping a call inside a closure are two possible solutions to overcome the immediate evaluation of arguments and receivers.</p> <p>In a <code>defer</code> function the arguments are evaluated right away, not once the surrounding function returns. For example, in this code, we always call <code>notify</code> and <code>incrementCounter</code> with the same status: an empty string.</p> <pre><code>const (\n    StatusSuccess  = \"success\"\n    StatusErrorFoo = \"error_foo\"\n    StatusErrorBar = \"error_bar\"\n)\n\nfunc f() error {\n    var status string\n    defer notify(status)\n    defer incrementCounter(status)\n\n    if err := foo(); err != nil {\n        status = StatusErrorFoo\n        return err\n    }\n\n    if err := bar(); err != nil {\n        status = StatusErrorBar\n        return err\n    }\n\n    status = StatusSuccess &lt;5&gt;\n    return nil\n}\n</code></pre> <p>Indeed, we call <code>notify(status)</code> and <code>incrementCounter(status)</code> as <code>defer</code> functions. Therefore, Go will delay these calls to be executed once <code>f</code> returns with the current value of status at the stage we used defer, hence passing an empty string.</p> <p>Two leading options if we want to keep using <code>defer</code>.</p> <p>The first solution is to pass a string pointer:</p> <pre><code>func f() error {\n    var status string\n    defer notify(&amp;status) \n    defer incrementCounter(&amp;status)\n\n    // The rest of the function unchanged\n    if err := foo(); err != nil {\n        status = StatusErrorFoo\n        return err\n    }\n\n    if err := bar(); err != nil {\n        status = StatusErrorBar\n        return err\n    }\n\n    status = StatusSuccess\n    return nil\n}\n</code></pre> <p>Using <code>defer</code> evaluates the arguments right away: here, the address of status. Yes, status itself is modified throughout the function, but its address remains constant, regardless of the assignments. Hence, if <code>notify</code> or <code>incrementCounter</code> uses the value referenced by the string pointer, it will work as expected. But this solution requires changing the signature of the two functions, which may not always be possible.</p> <p>There\u2019s another solution: calling a closure (an anonymous function value that references variables from outside its body) as a <code>defer</code> statement:</p> <pre><code>func f() error {\n    var status string\n    defer func() {\n        notify(status)\n        incrementCounter(status)\n    }()\n\n    // The rest of the function unchanged\n}\n</code></pre> <p>Here, we wrap the calls to both <code>notify</code> and <code>incrementCounter</code> within a closure. This closure references the status variable from outside its body. Therefore, <code>status</code> is evaluated once the closure is executed, not when we call <code>defer</code>. This solution also works and doesn\u2019t require <code>notify</code> and <code>incrementCounter</code> to change their signature.</p> <p>Let's also note this behavior applies with method receiver: the receiver is evaluated immediately.</p> <p>Source code</p>"},{"location":"mistakes/#error-management","title":"Error Management","text":""},{"location":"mistakes/#panicking-48","title":"Panicking (#48)","text":"<p>TL;DR: Using <code>panic</code> is an option to deal with errors in Go. However, it should only be used sparingly in unrecoverable conditions: for example, to signal a programmer error or when you fail to load a mandatory dependency.</p> <p>In Go, panic is a built-in function that stops the ordinary flow:</p> <pre><code>func main() {\n    fmt.Println(\"a\")\n    panic(\"foo\")\n    fmt.Println(\"b\")\n}\n</code></pre> <p>This code prints a and then stops before printing b:</p> <pre><code>a\npanic: foo\n\ngoroutine 1 [running]:\nmain.main()\n        main.go:7 +0xb3\n</code></pre> <p>Panicking in Go should be used sparingly. There are two prominent cases, one to signal a programmer error (e.g., <code>sql.Register</code> that panics if the driver is <code>nil</code> or has already been register) and another where our application fails to create a man- datory dependency. Hence, exceptional conditions that lead us to stop the application. In most other cases, error management should be done with a function that returns a proper error type as the last return argument.</p> <p>Source code</p>"},{"location":"mistakes/#ignoring-when-to-wrap-an-error-49","title":"Ignoring when to wrap an error (#49)","text":"<p>TL;DR: Wrapping an error allows you to mark an error and/or provide additional context. However, error wrapping creates potential coupling as it makes the source error available for the caller. If you want to prevent that, don\u2019t use error wrapping.</p> <p>Since Go 1.13, the %w directive allows us to wrap errors conveniently. Error wrapping is about wrapping or packing an error inside a wrapper container that also makes the source error available. In general, the two main use cases for error wrapping are the following:</p> <ul> <li>Adding additional context to an error</li> <li>Marking an error as a specific error</li> </ul> <p>When handling an error, we can decide to wrap it. Wrapping is about adding additional context to an error and/or marking an error as a specific type. If we need to mark an error, we should create a custom error type. However, if we just want to add extra context, we should use fmt.Errorf with the %w directive as it doesn\u2019t require creating a new error type. Yet, error wrapping creates potential coupling as it makes the source error available for the caller. If we want to prevent it, we shouldn\u2019t use error wrapping but error transformation, for example, using fmt.Errorf with the %v directive.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-an-error-type-inaccurately-50","title":"Comparing an error type inaccurately (#50)","text":"<p>TL;DR: If you use Go 1.13 error wrapping with the <code>%w</code> directive and <code>fmt.Errorf</code>, comparing an error against a type has to be done using <code>errors.As</code>. Otherwise, if the returned error you want to check is wrapped, it will fail the checks.</p> <p>Source code</p>"},{"location":"mistakes/#comparing-an-error-value-inaccurately-51","title":"Comparing an error value inaccurately (#51)","text":"<p>TL;DR: If you use Go 1.13 error wrapping with the <code>%w</code> directive and <code>fmt.Errorf</code>, comparing an error against or a value has to be done using <code>errors.As</code>. Otherwise, if the returned error you want to check is wrapped, it will fail the checks.</p> <p>A sentinel error is an error defined as a global variable:</p> <pre><code>import \"errors\"\n\nvar ErrFoo = errors.New(\"foo\")\n</code></pre> <p>In general, the convention is to start with <code>Err</code> followed by the error type: here, <code>ErrFoo</code>. A sentinel error conveys an expected error, an error that clients will expect to check. As general guidelines:</p> <ul> <li>Expected errors should be designed as error values (sentinel errors): <code>var ErrFoo = errors.New(\"foo\")</code>.</li> <li>Unexpected errors should be designed as error types: <code>type BarError struct { ... }</code>, with <code>BarError</code> implementing the <code>error</code> interface.</li> </ul> <p>If we use error wrapping in our application with the <code>%w</code> directive and <code>fmt.Errorf</code>, checking an error against a specific value should be done using <code>errors.Is</code> instead of <code>==</code>. Thus, even if the sentinel error is wrapped, <code>errors.Is</code> can recursively unwrap it and compare each error in the chain against the provided value.</p> <p>Source code</p>"},{"location":"mistakes/#handling-an-error-twice-52","title":"Handling an error twice (#52)","text":"<p>TL;DR: In most situations, an error should be handled only once. Logging an error is handling an error. Therefore, you have to choose between logging or returning an error. In many cases, error wrapping is the solution as it allows you to provide additional context to an error and return the source error.</p> <p>Handling an error multiple times is a mistake made frequently by developers, not spe- cifically in Go. This can cause situations where the same error is logged multiple times make debugging harder.</p> <p>Let's reming us that handling an error should be done only once. Logging an error is handling an error. Hence, we should either log or return an error. By doing this, we simplify our code and gain better insights into the error situation. Using error wrap- ping is the most convenient approach as it allows us to propagate the source error and add context to an error.</p> <p>Source code</p>"},{"location":"mistakes/#not-handling-an-error-53","title":"Not handling an error (#53)","text":"<p>TL;DR: Ignoring an error, whether during a function call or in a <code>defer</code> function, should be done explicitly using the blank identifier. Otherwise, future readers may be confused about whether it was intentional or a miss.</p> <p>Source code</p>"},{"location":"mistakes/#not-handling-defer-errors-54","title":"Not handling <code>defer</code> errors (#54)","text":"<p>TL;DR: In many cases, you shouldn\u2019t ignore an error returned by a <code>defer</code> function. Either handle it directly or propagate it to the caller, depending on the context. If you want to ignore it, use the blank identifier.</p> <p>Consider the following code:</p> <pre><code>func f() {\n  // ...\n  notify() // Error handling is omitted\n}\n\nfunc notify() error {\n  // ...\n}\n</code></pre> <p>From a maintainability perspective, the code can lead to some issues. Let\u2019s consider a new reader looking at it. This reader notices that notify returns an error but that the error isn\u2019t handled by the parent function. How can they guess whether or not handling the error was intentional? How can they know whether the previous developer forgot to handle it or did it purposely?</p> <p>For these reasons, when we want to ignore an error, there's only one way to do it, using the blank identifier (<code>_</code>):</p> <pre><code>_ = notify\n</code></pre> <p>In terms of compilation and run time, this approach doesn\u2019t change anything compared to the first piece of code. But this new version makes explicit that we aren\u2019t interested in the error. Also, we can add a comment that indicates the rationale for why an error is ignored:</p> <pre><code>// At-most once delivery.\n// Hence, it's accepted to miss some of them in case of errors.\n_ = notify()\n</code></pre> <p>Source code</p>"},{"location":"mistakes/#concurrency-foundations","title":"Concurrency: Foundations","text":""},{"location":"mistakes/#mixing-up-concurrency-and-parallelism-55","title":"Mixing up concurrency and parallelism (#55)","text":"<p>TL;DR: Understanding the fundamental differences between concurrency and parallelism is a cornerstone of the Go developer\u2019s knowledge. Concurrency is about structure, whereas parallelism is about execution.</p>"},{"location":"mistakes/#thinking-concurrency-is-always-faster-56","title":"Thinking concurrency is always faster (#56)","text":"<p>TL;DR: To be a proficient developer, you must acknowledge that concurrency isn\u2019t always faster. Solutions involving parallelization of minimal workloads may not necessarily be faster than a sequential implementation. Benchmarking sequential versus concurrent solutions should be the way to validate assumptions.</p> <p>Source code</p>"},{"location":"mistakes/#being-puzzled-about-when-to-use-channels-or-mutexes-57","title":"Being puzzled about when to use channels or mutexes (#57)","text":"<p>TL;DR: Being aware of goroutine interactions can also be helpful when deciding between channels and mutexes. In general, parallel goroutines require synchronization and hence mutexes. Conversely, concurrent goroutines generally require coordination and orchestration and hence channels.</p>"},{"location":"mistakes/#not-understanding-race-problems-data-races-vs-race-conditions-and-the-go-memory-model-58","title":"Not understanding race problems (data races vs. race conditions and the Go memory model) (#58)","text":"<p>TL;DR: Being proficient in concurrency also means understanding that data races and race conditions are different concepts. Data races occur when multiple goroutines simultaneously access the same memory location and at least one of them is writing. Meanwhile, being data-race-free doesn\u2019t necessarily mean deterministic execution. When a behavior depends on the sequence or the timing of events that can\u2019t be controlled, this is a race condition.</p> <p>Understanding the Go memory model and the underlying guarantees in terms of ordering and synchronization is essential to prevent possible data races and/or race conditions.</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-the-concurrency-impacts-of-a-workload-type-59","title":"Not understanding the concurrency impacts of a workload type (#59)","text":"<p>TL;DR: When creating a certain number of goroutines, consider the workload type. Creating CPU-bound goroutines means bounding this number close to the <code>GOMAXPROCS</code> variable (based by default on the number of CPU cores on the host). Creating I/O-bound goroutines depends on other factors, such as the external system.</p> <p>Source code</p>"},{"location":"mistakes/#misunderstanding-go-contexts-60","title":"Misunderstanding Go contexts (#60)","text":"<p>TL;DR: Go contexts are also one of the cornerstones of concurrency in Go. A context allows you to carry a deadline, a cancellation signal, and/or a list of keys-values.</p> <p>Source code</p>"},{"location":"mistakes/#concurrency-practice","title":"Concurrency: Practice","text":""},{"location":"mistakes/#propagating-an-inappropriate-context-61","title":"Propagating an inappropriate context (#61)","text":"<p>TL;DR: Understanding the conditions when a context can be canceled should matter when propagating it: for example, an HTTP handler canceling the context when the response has been sent.</p> <p>Source code</p>"},{"location":"mistakes/#starting-a-goroutine-without-knowing-when-to-stop-it-62","title":"Starting a goroutine without knowing when to stop it (#62)","text":"<p>TL;DR: Avoiding leaks means being mindful that whenever a goroutine is started, you should have a plan to stop it eventually.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-careful-with-goroutines-and-loop-variables-63","title":"Not being careful with goroutines and loop variables (#63)","text":"<p>TL;DR: To avoid bugs with goroutines and loop variables, create local variables or call functions instead of closures.</p> <p>Source code</p>"},{"location":"mistakes/#expecting-a-deterministic-behavior-using-select-and-channels-64","title":"Expecting a deterministic behavior using select and channels (#64)","text":"<p>TL;DR: Understanding that <code>select</code> with multiple channels chooses the case randomly if multiple options are possible prevents making wrong assumptions that can lead to subtle concurrency bugs.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-notification-channels-65","title":"Not using notification channels (#65)","text":"<p>TL;DR: Send notifications using a <code>chan struct{}</code> type.</p>"},{"location":"mistakes/#not-using-nil-channels-66","title":"Not using nil channels (#66)","text":"<p>TL;DR: Using nil channels should be part of your concurrency toolset because it allows you to remove cases from <code>select</code> statements, for example.</p> <p>Source code</p>"},{"location":"mistakes/#being-puzzled-about-channel-size-67","title":"Being puzzled about channel size (#67)","text":"<p>TL;DR: Carefully decide on the right channel type to use, given a problem. Only unbuffered channels provide strong synchronization guarantees.</p> <p>You should have a good reason to specify a channel size other than one for buffered channels.</p>"},{"location":"mistakes/#forgetting-about-possible-side-effects-with-string-formatting-etcd-data-race-example-and-deadlock-68","title":"Forgetting about possible side effects with string formatting (etcd data race example and deadlock) (#68)","text":"<p>TL;DR: Being aware that string formatting may lead to calling existing functions means watching out for possible deadlocks and other data races.</p> <p>Source code</p>"},{"location":"mistakes/#creating-data-races-with-append-69","title":"Creating data races with append (#69)","text":"<p>TL;DR: Calling <code>append</code> isn\u2019t always data-race-free; hence, it shouldn\u2019t be used concurrently on a shared slice.</p> <p>Source code</p>"},{"location":"mistakes/#using-mutexes-inaccurately-with-slices-and-maps-70","title":"Using mutexes inaccurately with slices and maps (#70)","text":"<p>TL;DR: Remembering that slices and maps are pointers can prevent common data races.</p> <p>Source code</p>"},{"location":"mistakes/#misusing-syncwaitgroup-71","title":"Misusing <code>sync.WaitGroup</code> (#71)","text":"<p>TL;DR: To accurately use <code>sync.WaitGroup</code>, call the <code>Add</code> method before spinning up goroutines.</p> <p>Source code</p>"},{"location":"mistakes/#forgetting-about-synccond-72","title":"Forgetting about <code>sync.Cond</code> (#72)","text":"<p>TL;DR: You can send repeated notifications to multiple goroutines with <code>sync.Cond</code>.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-errgroup-73","title":"Not using <code>errgroup</code> (#73)","text":"<p>TL;DR: You can synchronize a group of goroutines and handle errors and contexts with the <code>errgroup</code> package.</p> <p>Source code</p>"},{"location":"mistakes/#copying-a-sync-type-74","title":"Copying a <code>sync</code> type (#74)","text":"<p>TL;DR: <code>sync</code> types shouldn\u2019t be copied.</p> <p>Source code</p>"},{"location":"mistakes/#standard-library","title":"Standard Library","text":""},{"location":"mistakes/#providing-a-wrong-time-duration-75","title":"Providing a wrong time duration (#75)","text":"<p>TL;DR: Remain cautious with functions accepting a <code>time.Duration</code>. Even though passing an integer is allowed, strive to use the time API to prevent any possible confusion.</p> <p>Source code</p>"},{"location":"mistakes/#timeafter-and-memory-leaks-76","title":"<code>time.After</code> and memory leaks (#76)","text":"<p>TL;DR: Avoiding calls to <code>time.After</code> in repeated functions (such as loops or HTTP handlers) can avoid peak memory consumption. The resources created by <code>time.After</code> are released only when the timer expires.</p> <p>Source code</p>"},{"location":"mistakes/#json-handling-common-mistakes-77","title":"JSON handling common mistakes (#77)","text":"<ul> <li>Unexpected behavior because of type embedding</li> </ul> <p>Be careful about using embedded fields in Go structs. Doing so may lead to sneaky bugs like an embedded time.Time field implementing the <code>json.Marshaler</code> interface, hence overriding the default marshaling behavior.</p> <p>Source code</p> <ul> <li>JSON and the monotonic clock</li> </ul> <p>When comparing two <code>time.Time</code> structs, recall that <code>time.Time</code> contains both a wall clock and a monotonic clock, and the comparison using the == operator is done on both clocks.</p> <p>Source code</p> <ul> <li>Map of <code>any</code></li> </ul> <p>To avoid wrong assumptions when you provide a map while unmarshaling JSON data, remember that numerics are converted to <code>float64</code> by default.</p> <p>Source code</p>"},{"location":"mistakes/#common-sql-mistakes-78","title":"Common SQL mistakes (#78)","text":"<ul> <li>Forgetting that <code>sql.Open</code> doesn't necessarily establish connections to a database</li> </ul> <p>Call the <code>Ping</code> or <code>PingContext</code> method if you need to test your configuration and make sure a database is reachable.</p> <p>Source code</p> <ul> <li>Forgetting about connections pooling</li> </ul> <p>Configure the database connection parameters for production-grade applications.</p> <ul> <li>Not using prepared statements</li> </ul> <p>Using SQL prepared statements makes queries more efficient and more secure.</p> <p>Source code</p> <ul> <li>Mishandling null values</li> </ul> <p>Deal with nullable columns in tables using pointers or <code>sql.NullXXX</code> types.</p> <p>Source code</p> <ul> <li>Not handling rows iteration errors</li> </ul> <p>Call the <code>Err</code> method of <code>sql.Rows</code> after row iterations to ensure that you haven\u2019t missed an error while preparing the next row.</p> <p>Source code</p>"},{"location":"mistakes/#not-closing-transient-resources-http-body-sqlrows-and-osfile-79","title":"Not closing transient resources (HTTP body, <code>sql.Rows</code>, and <code>os.File</code>) (#79)","text":"<p>TL;DR: Eventually close all structs implementing <code>io.Closer</code> to avoid possible leaks.</p> <p>Source code</p>"},{"location":"mistakes/#forgetting-the-return-statement-after-replying-to-an-http-request-80","title":"Forgetting the return statement after replying to an HTTP request (#80)","text":"<p>TL;DR: To avoid unexpected behaviors in HTTP handler implementations, make sure you don\u2019t miss the <code>return</code> statement if you want a handler to stop after <code>http.Error</code>.</p> <p>Source code</p>"},{"location":"mistakes/#using-the-default-http-client-and-server-81","title":"Using the default HTTP client and server (#81)","text":"<p>TL;DR: For production-grade applications, don\u2019t use the default HTTP client and server implementations. These implementations are missing timeouts and behaviors that should be mandatory in production.</p> <p>Source code</p>"},{"location":"mistakes/#testing","title":"Testing","text":""},{"location":"mistakes/#not-categorizing-tests-build-tags-environment-variables-and-short-mode-82","title":"Not categorizing tests (build tags, environment variables, and short mode) (#82)","text":"<p>TL;DR: Categorizing tests using build flags, environment variables, or short mode makes the testing process more efficient. You can create test categories using build flags or environment variables (for example, unit versus integration tests) and differentiate short from long-running tests to decide which kinds of tests to execute.</p> <p>Source code</p>"},{"location":"mistakes/#not-enabling-the-race-flag-83","title":"Not enabling the race flag (#83)","text":"<p>TL;DR: Enabling the <code>-race</code> flag is highly recommended when writing concurrent applications. Doing so allows you to catch potential data races that can lead to software bugs.</p>"},{"location":"mistakes/#not-using-test-execution-modes-parallel-and-shuffle-84","title":"Not using test execution modes (parallel and shuffle) (#84)","text":"<p>TL;DR: Using the <code>-parallel</code> flag is an efficient way to speed up tests, especially long-running ones. Use the <code>-shuffle</code> flag to help ensure that a test suite doesn\u2019t rely on wrong assumptions that could hide bugs.</p>"},{"location":"mistakes/#not-using-table-driven-tests-85","title":"Not using table-driven tests (#85)","text":"<p>TL;DR: Table-driven tests are an efficient way to group a set of similar tests to prevent code duplication and make future updates easier to handle.</p> <p>Source code</p>"},{"location":"mistakes/#sleeping-in-unit-tests-86","title":"Sleeping in unit tests (#86)","text":"<p>TL;DR: Avoid sleeps using synchronization to make a test less flaky and more robust. If synchronization isn\u2019t possible, consider a retry approach.</p> <p>Source code</p>"},{"location":"mistakes/#not-dealing-with-the-time-api-efficiently-87","title":"Not dealing with the time API efficiently (#87)","text":"<p>TL;DR: Understanding how to deal with functions using the time API is another way to make a test less flaky. You can use standard techniques such as handling the time as part of a hidden dependency or asking clients to provide it.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-testing-utility-packages-httptest-and-iotest-88","title":"Not using testing utility packages (<code>httptest</code> and <code>iotest</code>) (#88)","text":"<ul> <li>The <code>httptest</code> package is helpful for dealing with HTTP applications. It provides a set of utilities to test both clients and servers.</li> </ul> <p>Source code</p> <ul> <li>The <code>iotest</code> package helps write io.Reader and test that an application is tolerant to errors.</li> </ul> <p>Source code</p>"},{"location":"mistakes/#writing-inaccurate-benchmarks-89","title":"Writing inaccurate benchmarks (#89)","text":"<ul> <li>Not resetting or pausing the timer</li> </ul> <p>Use time methods to preserve the accuracy of a benchmark.</p> <p>Source code</p> <ul> <li>Making wrong assumptions about micro-benchmarks</li> </ul> <p>Increasing <code>benchtime</code> or using tools such as <code>benchstat</code> can be helpful when dealing with micro-benchmarks.</p> <p>Be careful with the results of a micro-benchmark if the system that ends up running the application is different from the one running the micro-benchmark.</p> <p>Source code</p> <ul> <li>Not being careful about compiler optimizations</li> </ul> <p>Make sure the function under test leads to a side effect, to prevent compiler optimizations from fooling you about the benchmark results.</p> <p>Source code</p> <ul> <li>Being fooled by the observer effect</li> </ul> <p>To prevent the observer effect, force a benchmark to re-create the data used by a CPU-bound function.</p> <p>Source code</p>"},{"location":"mistakes/#not-exploring-all-the-go-testing-features-90","title":"Not exploring all the Go testing features (#90)","text":"<ul> <li>Code coverage</li> </ul> <p>Use code coverage with the <code>-coverprofile</code> flag to quickly see which part of the code needs more attention.</p> <ul> <li>Testing from a different package</li> </ul> <p>Place unit tests in a different package to enforce writing tests that focus on an exposed behavior, not internals.</p> <p>Source code</p> <ul> <li>Utility functions</li> </ul> <p>Handling errors using the <code>*testing.T</code> variable instead of the classic <code>if err != nil</code> makes code shorter and easier to read.</p> <p>Source code</p> <ul> <li>Setup and teardown</li> </ul> <p>You can use setup and teardown functions to configure a complex environment, such as in the case of integration tests.</p> <p>Source code</p>"},{"location":"mistakes/#not-using-fuzzing-community-mistake","title":"Not using fuzzing (community mistake)","text":"<p>TL;DR: Fuzzing is an efficient strategy to detect random, unexpected, or malformed inputs to complex functions and methods in order to discover vulnerabilities, bugs, or even potential crashes.</p> <p>Credits: @jeromedoucet</p>"},{"location":"mistakes/#optimizations","title":"Optimizations","text":""},{"location":"mistakes/#not-understanding-cpu-caches-91","title":"Not understanding CPU caches (#91)","text":"<ul> <li>CPU architecture</li> </ul> <p>Understanding how to use CPU caches is important for optimizing CPU-bound applications because the L1 cache is about 50 to 100 times faster than the main memory.</p> <ul> <li>Cache line</li> </ul> <p>Being conscious of the cache line concept is critical to understanding how to organize data in data-intensive applications. A CPU doesn\u2019t fetch memory word by word; instead, it usually copies a memory block to a 64-byte cache line. To get the most out of each individual cache line, enforce spatial locality.</p> <p>Source code</p> <ul> <li>Slice of structs vs. struct of slices</li> </ul> <p>Source code</p> <ul> <li>Predictability</li> </ul> <p>Making code predictable for the CPU can also be an efficient way to optimize certain functions. For example, a unit or constant stride is predictable for the CPU, but a non-unit stride (for example, a linked list) isn\u2019t predictable.</p> <p>Source code</p> <ul> <li>Cache placement policy</li> </ul> <p>To avoid a critical stride, hence utilizing only a tiny portion of the cache, be aware that caches are partitioned.</p>"},{"location":"mistakes/#writing-concurrent-code-that-leads-to-false-sharing-92","title":"Writing concurrent code that leads to false sharing (#92)","text":"<p>TL;DR: Knowing that lower levels of CPU caches aren\u2019t shared across all the cores helps avoid performance-degrading patterns such as false sharing while writing concurrency code. Sharing memory is an illusion.</p> <p>Source code</p>"},{"location":"mistakes/#not-taking-into-account-instruction-level-parallelism-93","title":"Not taking into account instruction-level parallelism (#93)","text":"<p>TL;DR: Use instruction-level parallelism (ILP) to optimize specific parts of your code to allow a CPU to execute as many parallel instructions as possible. Identifying data hazards is one of the main steps.</p> <p>Source code</p>"},{"location":"mistakes/#not-being-aware-of-data-alignment-94","title":"Not being aware of data alignment (#94)","text":"<p>TL;DR: You can avoid common mistakes by remembering that in Go, basic types are aligned with their own size. For example, keep in mind that reorganizing the fields of a struct by size in descending order can lead to more compact structs (less memory allocation and potentially a better spatial locality).</p> <p>Source code</p>"},{"location":"mistakes/#not-understanding-stack-vs-heap-95","title":"Not understanding stack vs. heap (#95)","text":"<p>TL;DR: Understanding the fundamental differences between heap and stack should also be part of your core knowledge when optimizing a Go application. Stack allocations are almost free, whereas heap allocations are slower and rely on the GC to clean the memory.</p> <p>Source code</p>"},{"location":"mistakes/#not-knowing-how-to-reduce-allocations-api-change-compiler-optimizations-and-syncpool-96","title":"Not knowing how to reduce allocations (API change, compiler optimizations, and <code>sync.Pool</code>) (#96)","text":"<p>TL;DR: Reducing allocations is also an essential aspect of optimizing a Go application. This can be done in different ways, such as designing the API carefully to prevent sharing up, understanding the common Go compiler optimizations, and using <code>sync.Pool</code>.</p> <p>Source code</p>"},{"location":"mistakes/#not-relying-on-inlining-97","title":"Not relying on inlining (#97)","text":"<p>TL;DR: Use the fast-path inlining technique to efficiently reduce the amortized time to call a function.</p>"},{"location":"mistakes/#not-using-go-diagnostics-tooling-98","title":"Not using Go diagnostics tooling (#98)","text":"<p>TL;DR: Rely on profiling and the execution tracer to understand how an application performs and the parts to optimize.</p>"},{"location":"mistakes/#not-understanding-how-the-gc-works-99","title":"Not understanding how the GC works (#99)","text":"<p>TL;DR: Understanding how to tune the GC can lead to multiple benefits such as handling sudden load increases more efficiently.</p>"},{"location":"mistakes/#not-understanding-the-impacts-of-running-go-in-docker-and-kubernetes-100","title":"Not understanding the impacts of running Go in Docker and Kubernetes (#100)","text":"<p>TL;DR: To help avoid CPU throttling when deployed in Docker and Kubernetes, keep in mind that Go isn\u2019t CFS-aware.</p>"},{"location":"chinese/","title":"Index","text":"<p>TODO</p>"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index 0f8724e..5b176c9 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -1,3 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+    <url>
+         <loc>https://100go.co/</loc>
+         <lastmod>2023-09-12</lastmod>
+         <changefreq>daily</changefreq>
+    </url>
+    <url>
+         <loc>https://100go.co/jobs/</loc>
+         <lastmod>2023-09-12</lastmod>
+         <changefreq>daily</changefreq>
+    </url>
+    <url>
+         <loc>https://100go.co/mistakes/</loc>
+         <lastmod>2023-09-12</lastmod>
+         <changefreq>daily</changefreq>
+    </url>
+    <url>
+         <loc>https://100go.co/chinese/</loc>
+         <lastmod>2023-09-12</lastmod>
+         <changefreq>daily</changefreq>
+    </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index 336d0df..f1df1da 100644
Binary files a/site/sitemap.xml.gz and b/site/sitemap.xml.gz differ