Thursday, June 29, 2023

Preface

Recently, I was tasked with developing a console application. Yes, you read that right, a console application.

Senior software engineers may find this quite familiar, but as time marches on, the web has taken center stage in the software world. Nowadays, most software jobs revolve around web development, and console applications may seem like a relic of the past.

Nevertheless, I am here, writing this blog post, to document my journey in console application development.

Is there any best practice?

I think you can learn many best practices from famous UNIX apps. Such as git, dig, and nc. Just use them and study them thoroughly.

In my experience, the following 7 topics hold significant importance, and I will give explanations for each of them:

Help message
Arguments
Exit code
Stderr
Sanitize user input
Print out the value user filled in.
Interactive mode
Windows system pause

Help message a.k.a welcome message

Tell the user what can this app do! It’s important because the app name may not self-explain it.

Once your app is run without any args, you can show help message immediately (if not so long), this can reduce the step asking user to pass “-h” or “–help” to your app.

Here is an example from git:

➜  ~ git
usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--config-env=<name>=<envvar>] <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone     Clone a repository into a new directory
   init      Create an empty Git repository or reinitialize an existing one

Arguments

Do you know the difference between “-h” and “–help”?

- is for single character, called option.
-- is for a name with 1~3 words by hyphen separated, called long option.

In addition, we all know positional arguments can be used without - or --.

Exit code

The exit code is useful for users and caller apps to easily understand the result of execution.

Stderr & Colorful message

If your app encounters an error, ensure that you print those error messages to stderr. This facilitates the caller app in capturing and forwarding these error messages elsewhere.

Additionally, you can highlight these messages in different colors to make them easily noticeable to users at a glance.

(Note, in Windows 10 and later, color mode can be enable by SetConsoleMode().)

Sanitize user input

For security reasons, you MUST always sanitize user input!

Or, at least, strip the leading and trailing space & \n, it makes your app more robust.

Print out the value user filled in

For console app, users may be not quite sure about their input value. Because of escape character, space, hyphen, etc. Besides, if you sanitize the input, you can print out the sanitized result.

Print out users’ input make them have faith in your app! Also, make your debugging more easily 😃

Interactive mode

Do you really expect users to click on your app, only to see a window flash and then disappear?

For Linux users, terminal operations may be second nature, but for Windows users, this might seem confusing, leading to complaints about your app being broken.

So, when a user-friendly app receives no arguments, it can display a helpful message, followed by interactive prompts to guide the user in providing the necessary input.

Windows system pause

If you’re building a Windows console app, don’t forget to call system("pause") or getchar() at the end of your program. This can prevent console from disappearing immediately if a user uses double click to launch your app.

Terminal Display Performance

Some terminal app (especially Windows CMD.exe) exhibit poor performance in displaying output. This can significantly degrade your app’s performance as stdout/stderr waits for the terminal.

A workaround is to use a separate thread to print messages from the message queue, with the other threads solely responsible for delivering messages to the queue.

Summary

Always consider how users use your app and how to enhance their comfort.

As a newcomer with less than a year of experience in app development, I’m still in the process of learning these skills. Feel free to share any suggestions for improvement – your feedback is welcome!

Learning from Developing Console App