DEV Community: Babak K. Shandiz

Godoc-Lint: a linter for Go Doc Comments (godocs) [RE#16]

Babak K. Shandiz — Sun, 09 Mar 2025 15:07:04 +0000

I was in a break between jobs when I decided it’s time to tackle the idea I had for a long time; Godoc-Lint, a linter for Go Doc Comments (godocs). But before getting to Godoc-Lint, let’s talk about the problem.

Godocs and perfectionism

As a bit of context, Golang supports inline documentations (godocs), similar to JavaScript’s JSDoc or C#’s triple-slash comments (///). However, it’s much simpler/basic in features and structure. The thing is Golang (or gofmt to be more precise) does not enforce any restrictions on how to write godocs. That’s why Go developers usually drift off the style, almost unknowingly. For example, they may forget to document what a package does, or what a particular function is meant to be used for. It’s frustrating for the end users of their library/module to open up the browser and search the web or read the docs for their questions. Let alone the inconsistency that annoys those perfectionist maintainers of the project.

To see what I’m talking about, just imagine this simple file, foo.go:

// This package helps with a bunch of things.
package foo

// This prints a hey.
func Foo() {
    println("Hey")
}

At first sight, the it seems nicely documented with godocs. But in terms of standards and style, both godocs are not in a good shape. If we run the godoclint CLI, we’ll see why that is the case:

$ godoclint ./...
foo.go:1:1: package godoc should start with "Package foo "
foo.go:4:1: godoc should start with symbol name (pattern "((A|a|An|an|THE|The|the) )?%")

So the right use of godocs is something like this:

// Package foo helps with a bunch of things.
package foo

// Foo prints a hey.
func Foo() {
    println("Hey")
}

You’ll be amazed to see how many times people are breaking the godoc standard, which is well described in this official Golang document, Go Doc Comments.

Godoc-Lint

Godoc-Lint is now out to help with this issue. It comes with a number of predefined rules that aim to keep godocs consistent and in-style. To give it a try, you can download the CLI binary from the repo’s Releases page, or simply use the below go install command:

go install github.com/godoc-lint/godoc-lint/cmd/godoclint

Once installed, you can navigate into your Golang project directory, and run it like this:

godoclint ./...

This will run the linter on all packages in your project, with a sensible (i.e., less annoying, yet important) set of default rules. For more about the rules and configuration check out the repo’s README.

ℹ️ Note that on large code bases, when running godoclint for the first time it might take a bit, but further runs will be much faster.

About Regular Encounters

I’ve decided to record my daily encounters with professional issues on a somewhat regular basis. Not all of them are equally important/unique/intricate, but are indeed practical, real, and of course, textually minimal.

Optimize Postgres Containers for Testing [RE#15]

Babak K. Shandiz — Fri, 26 Jan 2024 00:31:00 +0000

Recently, I had this task of transferring our tests from using in-memory SQLite instances to Postgres containers. It seemed a like a pretty straightforward set of changes, until I realized it’s not. I had to fix some random unexpected issues down the road. But the biggest (and to be fair, the most expected) one was the poor performance of the tests after fully migrating to Postgres.

Long story short, after some Internet search and reading documentations, I ended up getting a good performance (very close to what we had with SQLite) using the docker-compose.yaml configuration below:

services:
  postgres:
    image: postgres
    restart: always
    ports:
      - 5432:5432
    # Remove the `tmpfs` key below, either:
    # - If you don't want to lose the data after the container stops/restarts.
    # - If the data can be too large for the memory.
    tmpfs:
      - /var/lib/postgresql/data
    # Since it's mainly used for testing purposes, it's okay to set fsync=off for
    # improved performance.
    command: -c fsync=off -c full_page_writes=off

The key points here are:

Using tmpfs : With tmpfs mounts, you can utilize memory (RAM) as the underlying filesystem storage for specific paths. Here I’ve used it to store Postgres data. This, of course, means there’s no real persistence in-place, therefore you will lose the data if the container stops/restarts. Also, you have to be careful with the size of the data, in case it could get close to your memory limits.
Applying -c fsync=off -c full_page_writes=off : If you don’t disable the fsync option, Postgres makes sure that updates are physically written to disk, which could be a great performance hit. As of official documentations, if you turn fsync off, you should also consider disabling full_page_writes.

Living in the Shell #24; chmod (Modify file/directory permissions)

Babak K. Shandiz — Fri, 06 Jan 2023 11:57:13 +0000

`chmod` 🔐

Modifies file/directory permissions (See here or here for more details).

Permission expressions are mostly formatted as [ugoa][+-=][rwx]:

Symbol	Meaning
`r`	Read
`w`	Write
`x`	Execute

Symbol	Meaning
`u`	User (owner of the file/directory)
`g`	Group (of the file/directory)
`o`	Other users/groups
`a`	All users/groups

Grant all permissions to everyone; `a+rwx` or `777`

chmod a+rwx some-file
# or
chmod 777 some-file

Make a file executable for everyone `+x`

chmod +x some-file
# or
chmod a+x some-file

Make a file executable only for the User (owner) `u+x`

chmod u+x some-file

Disallow Group and Others to read/write/execute `go-rwx`

chmod go-rwx some-file

Apply the same User (owner) permissions to the Group `=u`

chmod g=u some-file

Rewrite permissions for the Group and Others `=`

chmod go=rw some-file

Clear permissions for the Group and Others `=`

chmod go= some-file

Clear all permissions `=`

chmod a= some-file

About Living in the Shell

Obsessed with doing things in the shell, I’ve decided to share my daily struggles on living in the shell as terse but informative posts.

VS Code Extension to Pick Relevant Emojis for Git Commit Messages 🐛

Babak K. Shandiz — Fri, 19 Aug 2022 10:43:00 +0000

Emoji in git commit message

If you're VS Code user and also a fan of emojis, this new VS Code extension might appeal to you, especially if you've read and liked Emojis for Better Git Commit Messages for its exhaustive table of contextual emoji data which were gathered over years. This new extension is called Git-Emoji. What it does is to provide you with relevant emoji suggestions to add to your git commit messages. This short screen capture would show you how this extension works:

To install it, search for “Git-Emoji” in the extension sidebar and click on the Install button. Alternatively, you can also install it as follows:

Press Ctrl+P
Type in ext install git-emoji.vscode-git-emoji and press Enter/Return

Dataset

If you’re interested in the emoji/contextual data behind this extension, you can access the underlying dataset via git-emoji/dataset-js repository on GitHub. It’s also available as a NPM package; @git-emoji/dataset-js.

Hope you like this extension. 🍏

Living in the Shell #23; cut (Cut Text/Fields from Text Streams)

Babak K. Shandiz — Fri, 24 Dec 2021 18:38:36 +0000

`cut` ✂️

Cuts/extracts text/fields out of text streams.

⚠️ Index values are one-based.

Cut characters on a range `-c`

echo "Hello World\!\nGoodbye\!" | cut -c2-5

Takes characters at indices 2 through 5.
ello
oodb

Cut characters on a half-limited range `-c`

echo "Hello World\!\nGoodbye\!" | cut -c3-

Takes characters from indices 3 and afterwards.
llo World!
odbye!

Cut fields split by any delimiter `-f` & `-d`

echo "1,20,300\n40,500,6000\n700,8000,90000" | cut -f2,3 -d','

20,300
500,6000
8000,90000

Change fields delimiter `--output-delimiter`

echo "1,20,300\n40,500,6000\n700,8000,90000" | cut -f1- -d',' --output-delimiter '/'

1/20/300
40/500/6000
700/8000/90000

Invert selection `--complement`

echo "1,20,300\n40,500,6000\n700,8000,90000" | cut -f2,3 -d',' --complement

1
40
700

Living in the Shell #22; md5sum/shasum (Check/Compute MD5/SHA Checksum of Files)

Babak K. Shandiz — Thu, 23 Dec 2021 15:48:52 +0000

`md5sum`/`shasum` #️⃣

Checks/computes MD5/SHA checksum of files.

Compute MD5 checksum `md5sum`

md5sum ~/.bashrc ~/.zshrc ~/.profile

fc4231f666b25990eefc1c51917d7bb1  /home/babak/.bashrc
6688207953bbd9d20d487a9509a6c297  /home/babak/.zshrc
43f7dc02e7bfb5d40703b5cb94e274ce  /home/babak/.profile

Compute SHA1 checksum `shasum`

shasum ~/.bashrc ~/.zshrc ~/.profile

499460ce753fa4b02cbb8c7e0cb61b1a9583bcd9  /home/babak/.bashrc
2f195c1d8c86cf34e4bdbd947e76fc9cb0bc900e  /home/babak/.zshrc
63d1a74119f9a8a84fd930ed8341395e9ab867f0  /home/babak/.profile

Compute other SHA checksums `-a`

shasum -a 256 ~/.bashrc ~/.zshrc ~/.profile

25d3d9737d0773dd6ece3a3536205784ce099314d68721eb5a865e82af66495c  /home/babak/.bashrc
5db662d84b785f026d6613e7e187a4a9c9333c9a38acf49ea7a5e15f4bb203c8  /home/babak/.zshrc
4c532d3d8bb0988d61ac334b1ffc6302ba0aac350b0d5c98102c3c4c443602f9  /home/babak/.profile

ℹ️ Supported SHA types are: 1 (default), 224, 256, 384, 512, 512224, 512256

Create checksums file for later checks

shasum ~/.bashrc ~/.zshrc ~/.profile > SHA1SUMS
md5sum ~/.bashrc ~/.zshrc ~/.profile > MD5SUMS

Check checksums `--check`

shasum --check SHA1SUMS
md5sum --check MD5SUMS

/home/babak/.bashrc: OK
/home/babak/.zshrc: OK
/home/babak/.profile: OK

Living in the Shell #21; head (Display File Content From Beginning)

Babak K. Shandiz — Tue, 21 Dec 2021 20:41:12 +0000

`head` 📜

Displays file content from beginning.

Print first N lines of a file `-n`

head -n 5 ~/.bashrc

Print all but N last lines `-n -N`

tail -n -3 ~/.bashrc

Print first N bytes of a file `-c`

head -c 1k ~/.bashrc

Prints first 1k of file binary content.

Print all but N last bytes `-c -N`

tail -c -1k ~/.bashrc

Living in the Shell #20; tail (Display/Follow File Content)

Babak K. Shandiz — Mon, 20 Dec 2021 19:41:07 +0000

`tail` ⛵

Display or follow file content.

ℹ️ Here, following means streaming a file while it's being updated (appended).

ℹ️ You can use -c in place of -n in the following examples, to switch to binary offset selection.

Print bottom N lines of a file `-n`

tail -n 5 ~/.bashrc

Prints last 5 lines of ~/.bashrc

Print from N-th line afterwards `-n +N`

tail -n +3 ~/.bashrc

Prints ~/.bashrc from the 3rd line until the end.

Following `syslog` events `-f`

tail -f /var/log/syslog

Follows system logs (on Debian/Ubuntu).

Living in the Shell #19; df (Report Disk Free Space)

Babak K. Shandiz — Sat, 18 Dec 2021 19:55:20 +0000

`df` 💾

Reports disk free space.

See disk free space

df

Filesystem     1K-blocks      Used Available Use% Mounted on
tmpfs            1603540      2068   1601472   1% /run
/dev/nvme0n1p3 471738592 268747932 178957944  61% /
tmpfs            8017688    327492   7690196   5% /dev/shm
tmpfs               5120         4      5116   1% /run/lock
tmpfs               4096         0      4096   0% /sys/fs/cgroup
/dev/nvme0n1p1    244988      5304    239684   3% /boot/efi
tmpfs            1603536       120   1603416   1% /run/user/1000

Note that the values are in kilobytes.

Human-readable size values `-h`

df -h

Filesystem      Size  Used Avail Use% Mounted on
tmpfs           1.6G  2.1M  1.6G   1% /run
/dev/nvme0n1p3  450G  257G  171G  61% /
tmpfs           7.7G  313M  7.4G   4% /dev/shm
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
tmpfs           4.0M     0  4.0M   0% /sys/fs/cgroup
/dev/nvme0n1p1  240M  5.2M  235M   3% /boot/efi
tmpfs           1.6G  120K  1.6G   1% /run/user/1000

Include file-system type `-T`

df -hT

Filesystem     Type   Size  Used Avail Use% Mounted on
tmpfs          tmpfs  1.6G  2.1M  1.6G   1% /run
/dev/nvme0n1p3 ext4   450G  257G  171G  61% /
tmpfs          tmpfs  7.7G  296M  7.4G   4% /dev/shm
tmpfs          tmpfs  5.0M  4.0K  5.0M   1% /run/lock
tmpfs          tmpfs  4.0M     0  4.0M   0% /sys/fs/cgroup
/dev/nvme0n1p1 vfat   240M  5.2M  235M   3% /boot/efi
tmpfs          tmpfs  1.6G  120K  1.6G   1% /run/user/1000

Produce a grand total `--total`

df -h --total

Filesystem      Size  Used Avail Use% Mounted on
...
total           461G  257G  182G  59% -

Living in the Shell #18; du (Report Directory Size)

Babak K. Shandiz — Fri, 17 Dec 2021 18:53:15 +0000

`du` 💽

Reports disk usage.

See summarized directory size `-s`

du -s ~/Downloads

11732700        /home/babak/Downloads
Note that the result is in kilobytes.

Human-readable size values `-h`

du -sh ~/Downloads

12G   /home/babak/Downloads

Exclude files by pattern `--exclude`

du -sh --exclude '*.iso' ~/Downloads

7.1G   /home/babak/Downloads

See exhaustive sub-directory sizes

du ~/Documents

Limit recursion depth `-d`

du -h -d 1 ~/Documents

Include files in exhaustive size report `-a`

du -h -a ~/Documents

Living in the Shell #17; curl (HTTP/S Client) (Part 2)

Babak K. Shandiz — Thu, 16 Dec 2021 19:25:37 +0000

`curl` 🌐

Makes requests in various protocols, including (but not limited to) HTTP/HTTPS/FTP/FTPS.

Add a custom header to request `-H`

curl https://postman-echo.com/get -H 'user-agent: curl'

ℹ️ You can set any number of headers by repeating -H options.

Make a `POST` request with JSON body `-d` & `-X`

curl https://postman-echo.com/post \
    -X POST \
    -H 'content-type: application/json' \
    -d '{"key":"value"}'

{
  "args": {},
  "data": {
    "key": "value"
  },
  "files": {},
  "form": {},
  "headers": {
    "x-forwarded-proto": "https",
    "x-forwarded-port": "443",
    "host": "postman-echo.com",
    "x-amzn-trace-id": "Root=1-61ba2f8f-304430e917ea20e7024a87c3",
    "content-length": "15",
    "user-agent": "curl/7.74.0",
    "accept": "*/*",
    "content-type": "application/json"
  },
  "json": {
    "key": "value"
  },
  "url": "https://postman-echo.com/post"
}

Read request body from file `-d@`

curl https://postman-echo.com/post \
    -X POST \
    -H 'content-type: application/json' \
    -d @data-file.json

Read request headers from file `-H@`

curl https://postman-echo.com/post \
    -X POST \
    -H @headers-file.txt \
    -d @data-file.json

⚠️ The headers file should be formatted as "key: value" per line.

Make a `HEAD` request `-I`

curl -I https://postman-echo.com/get

ℹ️ Alternatively, you can use -X HEAD instead of -I.

See more detailed process logs `-v`

curl -v https://postman-echo.com/get

This will print more low-level details, including protocol handshakes and negotiations.

Living in the Shell #16; curl (HTTP/S Client) (Part 1)

Babak K. Shandiz — Wed, 15 Dec 2021 17:43:47 +0000

`curl` 🌐

Makes requests in various protocols, including (but not limited to) HTTP/HTTPS/FTP/FTPS.

Make a simple `GET` request

curl https://google.com

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="https://www.google.com/">here</A>.
</BODY></HTML>

Simple `GET` request with following redirects `-L`

curl -L https://google.com

Write response to a file `-o`

curl -L https://google.com -o content.html

Include response headers `-i`

curl -i -L https://google.com

HTTP/2 301 
location: https://www.google.com/
content-type: text/html; charset=UTF-8
date: Wed, 15 Dec 2021 17:45:16 GMT
expires: Fri, 14 Jan 2022 17:45:16 GMT
cache-control: public, max-age=2592000
server: gws
content-length: 220
x-xss-protection: 0
x-frame-options: SAMEORIGIN
...

Request via a HTTP proxy server `-x`

curl -L https://google.com -x proxy-server:port

Request via a SOCKS proxy server `--socks`

curl -L https://google.com --socks proxy-server:port

DEV Community: Babak K. Shandiz

Godoc-Lint: a linter for Go Doc Comments (godocs) [RE#16]

Godocs and perfectionism

Godoc-Lint

Optimize Postgres Containers for Testing [RE#15]

Living in the Shell #24; chmod (Modify file/directory permissions)

chmod 🔐

Grant all permissions to everyone; a+rwx or 777

Make a file executable for everyone +x

Make a file executable only for the User (owner) u+x

Disallow Group and Others to read/write/execute go-rwx

Apply the same User (owner) permissions to the Group =u

Rewrite permissions for the Group and Others =

Clear permissions for the Group and Others =

Clear all permissions =

VS Code Extension to Pick Relevant Emojis for Git Commit Messages 🐛

Emoji in git commit message

Dataset

Living in the Shell #23; cut (Cut Text/Fields from Text Streams)

cut ✂️

Cut characters on a range -c

Cut characters on a half-limited range -c

Cut fields split by any delimiter -f & -d

Change fields delimiter --output-delimiter

Invert selection --complement

Living in the Shell #22; md5sum/shasum (Check/Compute MD5/SHA Checksum of Files)

md5sum/shasum #️⃣

Compute MD5 checksum md5sum

Compute SHA1 checksum shasum

Compute other SHA checksums -a

Create checksums file for later checks

Check checksums --check

Living in the Shell #21; head (Display File Content From Beginning)

head 📜

Print first N lines of a file -n

Print all but N last lines -n -N

Print first N bytes of a file -c

Print all but N last bytes -c -N

Living in the Shell #20; tail (Display/Follow File Content)

tail ⛵

Print bottom N lines of a file -n

Print from N-th line afterwards -n +N

Following syslog events -f

Living in the Shell #19; df (Report Disk Free Space)

df 💾

See disk free space

Human-readable size values -h

Include file-system type -T

Produce a grand total --total

Living in the Shell #18; du (Report Directory Size)

du 💽

See summarized directory size -s

Human-readable size values -h

Exclude files by pattern --exclude

See exhaustive sub-directory sizes

Limit recursion depth -d

Include files in exhaustive size report -a

Living in the Shell #17; curl (HTTP/S Client) (Part 2)

curl 🌐

Add a custom header to request -H

Make a POST request with JSON body -d & -X

Read request body from file -d@

Read request headers from file -H@

Make a HEAD request -I

See more detailed process logs -v

Living in the Shell #16; curl (HTTP/S Client) (Part 1)

curl 🌐

Make a simple GET request

Simple GET request with following redirects -L

Write response to a file -o

Include response headers -i

Request via a HTTP proxy server -x

Request via a SOCKS proxy server --socks

`chmod` 🔐

Grant all permissions to everyone; `a+rwx` or `777`

Make a file executable for everyone `+x`

Make a file executable only for the User (owner) `u+x`

Disallow Group and Others to read/write/execute `go-rwx`

Apply the same User (owner) permissions to the Group `=u`

Rewrite permissions for the Group and Others `=`

Clear permissions for the Group and Others `=`

Clear all permissions `=`

`cut` ✂️

Cut characters on a range `-c`

Cut characters on a half-limited range `-c`

Cut fields split by any delimiter `-f` & `-d`

Change fields delimiter `--output-delimiter`

Invert selection `--complement`

`md5sum`/`shasum` #️⃣

Compute MD5 checksum `md5sum`

Compute SHA1 checksum `shasum`

Compute other SHA checksums `-a`

Check checksums `--check`

`head` 📜

Print first N lines of a file `-n`

Print all but N last lines `-n -N`

Print first N bytes of a file `-c`

Print all but N last bytes `-c -N`

`tail` ⛵

Print bottom N lines of a file `-n`

Print from N-th line afterwards `-n +N`

Following `syslog` events `-f`

`df` 💾

Human-readable size values `-h`

Include file-system type `-T`

Produce a grand total `--total`

`du` 💽

See summarized directory size `-s`

Human-readable size values `-h`

Exclude files by pattern `--exclude`

Limit recursion depth `-d`

Include files in exhaustive size report `-a`

`curl` 🌐

Add a custom header to request `-H`

Make a `POST` request with JSON body `-d` & `-X`

Read request body from file `-d@`

Read request headers from file `-H@`

Make a `HEAD` request `-I`

See more detailed process logs `-v`

`curl` 🌐

Make a simple `GET` request

Simple `GET` request with following redirects `-L`

Write response to a file `-o`

Include response headers `-i`

Request via a HTTP proxy server `-x`

Request via a SOCKS proxy server `--socks`