[RFC] The Symfony Console Style Guide

[javiereguiluz]

This is the proposal for the new Symfony Console Style Guide. Please review it as soon as you can, because the schedule is pretty tight. We'd like to update most of the commands for Symfony 2.6 version.

Download Symfony Console Style Guide (PDF, 89 KB)

[kbond]

I think there should always be 1 blank line before the result bar as well.

[javiereguiluz]

@kbond good catch! I've just updated the PDF.

[wouterj]

I like the direction the styleguide wants to guide you: Making outputs more consistent and clear. However, I don't like many concrete guides in the styleguide.

General

The behaviour of the current help command and the behaviour of the console component in general is based on the common standard defined as the docopt standard. I don't like it if we move away from that standard, the Symfony Styleguide should only extend it imo.

Specific points

• Title hierarchy is shown using the same styles as Markdown - The markdown syntax with underlines only supports 2 levels, is this intended (to limit complexiness)? Otherwise, I would suggest the reSt Symfony standard.
• I found the yellow dots to be confusing at first
• Result bars being full width are mentioned twice in page 3
• I don't like //. We can say there are 2 types of commands: Queries and Actions. For queries, the output of a command is the result of the query. In case of an action, the output is a message keeping the user up to date with the progress of the action. In both cases, the output is needed for the command to be user friendly.
  // indicates something that isn't needed in such cases, it has to be removed from the normal verbosity output and be moved to a more verbose output.
• Avoid line overflows when the contents are too long - We should define an exact maximum line length imo
• I'm -1 on putting the user input on a new line
• For confirmation questions, the common convention is to use [nY] (where yes is the default). I would add that to the styleguide.

Please don't take this as an attack on you. I like the time you're putting into the Symfony community and I like it that you're doing the first step on this. However, I just wanted to share my thoughts on the exact guide. (and as always, it's just my opinion, do with it whatever you like :P).

[kbond]

I would like to see some additional examples for Questions:

• Choice question
• Confirmation question
• Question with validation error

[kbond]

What about exceptions? How should they be styled?

[javiereguiluz]

@kbond thanks for noticing all these missing things. Let's do a recap here:

• Progress bars
• Other types of questions: choice, confirmation, question with error validation)
• Exceptions / Errors

[kbond]

Also, what about a "Warning" result bar that would be orange or yellow? Might be useful to show "OK but with some errors"

[javiereguiluz]

@kbond any existing command that you are aware of that needs that Warning result bar? I'd like to analyze the use case. Thanks.

[kbond]

I can't think of any in Symfony core but I can think a use case in one of the bundles I maintain. zenstruck/cache-bundle has a command that warms up the http cache by hitting a list of urls. If all the urls return 200, I would show green, if some returned !200, I would show orange, if all returned !200 I would show red.

[ThomasLomas]

I like this a lot. It will also help the community with keeping bundle commands consistent as well.

I like the question styles and it should also tie in nicely with symfony/symfony#11975 which shows the default answer to the user.

[javiereguiluz]

@wouterj first, it's impossible that I consider your comment as a personal attack. Everything in the Symfony community is debatable and I repeatedly asked for feedback (positive or negative). Constructive criticism is what's making us win, so keep 'em coming :)

There are a lot of things in your comment, so let's break into three big parts:

Quick comments

• Docopt: I don't understand this issue. The command help output is almost identical to that standard. Is there something else we could do?
• Title hierarchy: the syntax is Markdown or RST because we want to limit headings to 2 levels. Otherwise, some developers will overcomplicate things.
• Yellow dots: I don't know how to show the white spaces. I used the convention of IDEs. If someone is confused too: the yellow dots of the PDF are just for helping us; they won't appear in the console output.
• Long lines: very good catch! We need to set a maximum line length for the text dispalyed in ultra wide console widths. I propose to use 120 chars for that limit.

User Input in new line

The rationale for this is showed in this illustration:

Creating a new line for user input allows us to show a perfect alignment. The eye of the user doesn't jump from one point to another to scan the values he/she typed.

In addition, keep in mind that questions may show the default values and the allowed values. This can produce ultra long question lines that can break user input (that's ugly and confusing):

Information and debug messages

This is the most controversial part of the style guide so far. First, I confess that it's a completely personal opinion. I haven't seen this "feature" used anywhere.

Second, my rationale was like this: I like when things are self-explained. This is a title, this is an error message, this is the result of the command, etc. If this info messages don't include some distinctive design, they look like: "hey, here it is some random text. Who knows what's this?

See the illustration for a visual explanation:

[javiereguiluz]

I've just uploaded a new version which includes the Progress Bar styles.

[kbond]

A lot of commands add or remove files. Should the style guide contain standards for displaying this?