journal/2017: update on "Go (Informal) Coding Styles"

Expand the section about using short variable names.

While at it, add short section index.

1 files changed, 28 insertions, 10 deletions

diff --git a/_content/journal/2017/05/Go_Informal_Coding_Style/index.adoc b/_content/journal/2017/05/Go_Informal_Coding_Style/index.adoc
index 044f95e..6d89652 100644
--- a/_content/journal/2017/05/Go_Informal_Coding_Style/index.adoc
+++ b/_content/journal/2017/05/Go_Informal_Coding_Style/index.adoc
@@ -3,6 +3,8 @@
 
 =  Go (Informal) Coding Style
 Shulhan <ms@kilabit.info>
+12 May 2019
+:sectanchors:
 :toc:
 
 In general Go already have `gofmt` that will format the code according to Go
@@ -16,6 +18,8 @@ If you work in large code base, with more than three developers, you should
 already have a common "language" between them, to make it consistent and
 readable.
 
+
+[#group_imports]
 ==  Group imports
 
 Imported packages should be grouped and ordered by system, third party, and
@@ -35,6 +39,7 @@ import (
 ----
 
 
+[#code_structure]
 ==  Structure the code as in Godoc layout
 
 If you looks at the Godoc layout, each sections is ordered by the following
@@ -57,6 +62,7 @@ know where each of section is located.
 [1] https://pkg.go.dev/net/
 
 
+[#package_file]
 ==  Package should have a file with the same name
 
 Package `mypkg` should have source file with the name `mypkg.go`.
@@ -67,6 +73,7 @@ constants, and/or maybe `init()` function.
 defined.
 
 
+[#one_type_per_file]
 ==  One type (struct/interface) per file
 
 The filename should follow the name of the type.
@@ -79,6 +86,7 @@ So, in the directory `X` there would be two files: `y.go` and `z.go`.
 *  Modularization by files
 
 
+[#explicit_struct_field]
 ==  Define field name when creating struct instance
 
 Bad practice:
@@ -109,26 +117,28 @@ x := ADT{
 *  Easy to read.
 
 
+[#short_variable_name]
 ==  Use short variable names if possible
 
+Using one or two words in variable name is preferable.
+Using three or more characters in variable name is also preferable.
+
+Avoid three or more words, like `UserAccountProfile`, that could shortened
+into `AccoutProfile` or just `Profile` if no other possbile "profile" can be
+stored in the system.
+
 Common short variable names,
 
 *  `x`, `y`, and `z` for looping.
    Not `i`, `j`, etc. because its prone to typo, and let more than three deeps
-   looping (which is a signal for bad programming) and its not easy for quick
-   reading.
+   looping (`i`,`j`,`k`,`l`, ... which is a signal for bad programming) and
+   its not easy for quick reading.
 *  `err` for error variable
 *  `ctx` for context
 *  `req` for client request
 *  `res` for server response
 *  `msg` for general message input/output
 
-Common prefix for variable or function,
-
-*  `jXXX` for message in JSON struct
-*  `bXXX` for message in slice of bytes ([]byte)
-*  `DefXXX` or `defXXX` for default variable/constanta
-
 **Rationale:**
 
 * Searchability, find-and-replace with three characters is more easy than
@@ -137,6 +147,7 @@ Common prefix for variable or function,
   body.
 
 
+[#comment_grammar]
 ==  Comment grammar 
 
 In Go, exported field or function denoted by capital letter on the first
@@ -166,6 +177,7 @@ func GetEnv(envName string) (v string, err error) {
 ----
 
 
+[#cmd_package]
 ==  Package that create binary should be in "cmd" directory
 
 One of the things that I learned later in software development was when
@@ -178,6 +190,7 @@ Go, in subtle way, embrace this kind of thinking when developing
 software.
 
 
+[#logging_level]
 == Log on service level, not on library
 
 Let say that we have HTTP service on package `service/myhttp` that use
@@ -231,7 +244,8 @@ Centralizing the error on service level help us to forward the error to other
 output/services without modify or import third party module on library level.
 
 
-== Avoid ":=" if possible
+[#avoid_short_assignment]
+== Avoid short assigment if possible
 
 _Why?_
 
@@ -247,7 +261,7 @@ x := f()
 ----
 
 To know what type of `x`, I need to search and check the signature of `f`.
-If we declare they variable type, it will save time for reader.
+If we explicitly declare the variable type, it will save time for reader.
 
 ----
 var x T = f()
@@ -288,6 +302,7 @@ and not-easy to read code [1][2].
 [2] https://github.com/golang/go/issues/377
 
 
+[#raw_string_literal]
 ==  Use raw literal string when possible
 
 https://go.dev/ref/spec#String_literals[Raw literal string] use backtick (\``)
@@ -298,6 +313,7 @@ It may improve the build time, but I don't have the data or code to support
 this, so take this with grain of salt.
 
 
+[#prefer_test_example]
 ==  Create test Example over unit test if possible
 
 A test Example, the function in `_test.go` file that have Example prefix, is
@@ -307,6 +323,7 @@ documentation.
 So, pretty much killing two birds with one stone.
 
 
+[#separate_test_example]
 ==  Test example should be on separate file
 
 If package x has test file `x_test.go`, any test Example for that package
@@ -316,6 +333,7 @@ This is to allow the file to use different package name `x_test` instead of
 `x` (see below) and searchable by human eyes.
 
 
+[#separate_test_package_for_example]
 ==  Use _test suffix in package name for Example
 
 Package name in test Example should be different with the actual package.