2

How do you prefer to format output of your console scripts? I mean output produced during application run (log, stdout).

BG: I have a python script that takes a data, processes it, updates some related data in my database and outputs progress. I can style output in various ways:

************ Starting programm X ************
Fetching 450 lands... Done
540 local lands found
syncronizing [--------                ] 10%
Done

Capitalized output or all letters in lower case? Indentation applied to output or not? What about visual sugar like dashes or hashes? Progress bars like in wget?

I understand that it's kind of design, but in Web we have some basic rules, we have usability, and we have no rules in console output art. What Jacob Nilsen says about output of console scripts?

Dmitry P.
  • 356
  • 2
  • 13
  • 1
    Applications should fail loudly and succeed quietly. The best output is no output. – William Pursell Oct 05 '13 at 03:51
  • @WilliamPursell awesome words! Totally agreed. – aIKid Oct 05 '13 at 04:05
  • Progress bar is nice, but the rest might be better in a log (with verbose optional). Plan for your output to be parseable and pipeable. – kalhartt Oct 05 '13 at 04:05
  • If these things are slow, or if it's hard to tell when it's making progress vs. when it's stalled, having all that feedback can be useful. (See, e.g., `ffmpeg` for an example… although it's definitely very excessive, _some_ of what it dumps to stderr, you wouldn't want to live without.) – abarnert Oct 05 '13 at 05:12

1 Answers1

2

Usability is very important even in console scripts. In particular with any long running process whether the UI is graphical or in a terminal it is better usability to show some indication of the progress of the task. I would recommend looking at Nielsen's heuristics many of the principles are directly applicable to console output. There are three heuristics in particular when talking about console output that may be useful to look at:

  1. Visibility of system status: Display progress in the console through some sort of progress bar to show what is going on within reasonable time.
  2. Consistency and standards: You touched upon this in your question dashes or hashes.
  3. Aesthetic and minimalist design: Try and output the minimum amount of information that is relevant and useful.

For standards and consistency go with the conventions of existing popular commands. Two good ones to check out are wget and pv. Both of them have very similar looking progressbars:

wget

44% [================>                      ] 441,017,992  111MB/s  eta 6s

pv

 138MB 0:00:01 [ 107MB/s] [=========================================>] 100%

They both generally look the same. They also adhere to minimal design in that in one line they indicate the percent complete in text and bar form, the speed, the bytes completed and the eta or time elapsed.

In terms of updating in reasonable time. I tend to update status in a console every 0.1 seconds. For an interface to feel responsive you want it something in that range. wget seems to be updating every 0.2 seconds. But the default for the command watch is 2s which feels too sluggish. I usually end up running that command as watch -n 0.1 command to have a 0.1s update interval.

One of the comments pointed out that your output should be parseable and pipeable. This is a very nice thing to have if possible. I particularly like the way wget approaches this issue. If you run wget in a terminal it uses the bar progress indicator but if you pipe to a file or another program it uses the dot progress indicator. It detects whether you have a tty or are piping the command automatically and chooses the most appropriate format. You can read about this on it's man page under the --progress argument documentation. Essentially it has one output that is more human readable and another that is more machine readable and log friendly.

Some related/useful links:

Community
  • 1
  • 1
Marwan Alsabbagh
  • 25,364
  • 9
  • 55
  • 65