Saída de programas e de erros produzidos não deveriam estar sendo formatados como citação - Stack Overflow em Português Meta
Tenho visto uma tendência um tanto irritante na formatação de mensagens de saída, em especial de erros. A saída pode aparecer nas perguntas e respostas aqui do StackOverflow formatada de diversas formas, sendo as três principais as seguintes:
Sem nenhuma formatação;
Serem formatados como citação ou;
Serem formatados como código-fonte.
Usuários novos tendem a postar a saída com os erros diretamente no editor sem formá-la de forma adequada, pois eles tendem apenas a copiar-e-colar o erro no editor. Isso ocorre porque eles não estão habituados a usar o editor daqui e não conhecem o seu comportamento.
Usuários mais experientes ou os editores que vierem a tentar arrumar a formatação do usuário novo irão optar por uma das últimas duas formas citadas acima.
Entretanto, eu acredito que a formatação como citação seja inadequada porque destrói a informação de indentação existente nas mensagens de erro ou de saída. Os exemplos que coloco abaixo mostram o porque essa indentação é importante.
Eis abaixo alguns exemplos reais:
Eis o que o usuário postou originalmente:
prog.c: In function 'main': prog.c:18:39: error: array subscript is not an integer if (aux_st == 0) ponto[i][j] = 246; ^ prog.c:7:12: warning: variable 'ponto' set but not used [-Wunused-but-set-variable] float ponto[MAX][MAX];
Então, após isso, alguém formata como citação:
Eu formatei como código-fonte, utilizando o <!-- language: none --> antes do respectivo código:
prog.c:18:39: error: array subscript is not an integer
if (aux_st == 0) ponto[i][j] = 246;
prog.c:7:12: warning: variable 'ponto' set but not used [-Wunused-but-set-variable]
float ponto[MAX][MAX];
Observe que a saída (no caso um erro de compilação) inclui indentação do código-fonte e a linha com o ^ que aponta a coluna onde ocorreu o erro. Esses detalhes são destruídos pela formatação em citação.
Eis o que o usuário postou:
//Código do erro no Terminal
src/com/example/web/BeerSelect.java:3: error: package javax.servlet does not exist import javax.servlet.; ^ src/com/example/web/BeerSelect.java:4: error: package javax.servlet.http does not exist import javax.servlet.http.; ^ src/com/example/web/BeerSelect.java:7: error: cannot find symbol public class BeerSelect extends HttpServlet { ^ symbol: class HttpServlet src/com/example/web/BeerSelect.java:9: error: cannot find symbol public void doPost ( HttpServletRequest request, ^ symbol: class HttpServletRequest location: class BeerSelect src/com/example/web/BeerSelect.java:10: error: cannot find symbol HttpServletResponse response ) ^ symbol: class HttpServletResponse location: class BeerSelect src/com/example/web/BeerSelect.java:11: error: cannot find symbol throws IOException , ServletException{ ^ symbol: class ServletException location: class BeerSelect 6 errors
Depois, um outro usuário formatou como citação:
Depois, eu formatei como código:
src/com/example/web/BeerSelect.java:3: error: package javax.servlet does not exist
src/com/example/web/BeerSelect.java:4: error: package javax.servlet.http does not exist
src/com/example/web/BeerSelect.java:7: error: cannot find symbol
public class BeerSelect  extends HttpServlet {
src/com/example/web/BeerSelect.java:9: error: cannot find symbol
public void doPost ( HttpServletRequest request,
symbol:   class HttpServletRequest
src/com/example/web/BeerSelect.java:10: error: cannot find symbol
symbol:   class HttpServletResponse
src/com/example/web/BeerSelect.java:11: error: cannot find symbol
symbol:   class ServletException
Este caso é similar ao primeiro. A indentação contém detalhes importantes que são destruídos pela formatação em citação.
Stacktrace postado pelo usuário:
at Soma.(Main.java:37)
Formatado como citação por um moderador:
Como eu acho que deveria ter sido formatado:
at Soma.<init>(Main.java:37)
Como o usuário formatou originalmente (já em código-fonte, mas com coloração de sintaxe inadequada):
Exception in thread "main" javax.persistence.PersistenceException: org.hibernate.PersistentObjectException: detached entity passed to persist: br.com.arena.model.Pessoa
at br.com.arena.dao.PessoaTimeDAO.cadastrar(PessoaTimeDAO.java:18)
at br.com.arena.util.Persistir.main(Persistir.java:54)
Caused by: org.hibernate.PersistentObjectException: detached entity passed to persist: br.com.arena.model.Pessoa
at org.hibernate.event.def.DefaultPersistEventListener.onPersist(DefaultPersistEventListener.java:102)
Um usuário editou e "simplificou" o erro. O problema é que daí a mensagem de erro deixa de ser uma expressão fiel da verdade, pois não mais corresponde a saída do programa como ela foi dada (mas isso já é um outro problema):
E um outro usuário formatou como citação:
Exception in thread "main" javax.persistence.PersistenceException: org.hibernate.PersistentObjectException: detached entity passed to persist: br.com.arena.model.Pessoa at org.hibernate.ejb.AbstractEntityManagerImpl.throwPersistenceException(AbstractEntityManagerImpl.java:614) at org.hibernate.ejb.AbstractEntityManagerImpl.persist(AbstractEntityManagerImpl.java:226) at br.com.arena.dao.PessoaTimeDAO.cadastrar(PessoaTimeDAO.java:18) at br.com.arena.util.Persistir.main(Persistir.java:54) Caused by: org.hibernate.PersistentObjectException: detached entity passed to persist: br.com.arena.model.Pessoa at org.hibernate.event.def.DefaultPersistEventListener.onPersist(DefaultPersistEventListener.java:102) at org.hibernate.impl.SessionImpl.firePersist(SessionImpl.java:636) at org.hibernate.impl.SessionImpl.persist(SessionImpl.java:628) at org.hibernate.engine.EJB3CascadingAction$1.cascade(EJB3CascadingAction.java:28) ... 18 more
Ocorre que ao formatar o stacktrace como citação, o mesmo perdeu qualidade de formatação ao invés de ganhar e tornou-se mais difícil de ser lido e entendido ao invés de mais fácil.
SEMPRE formatar a saída de programas como código-fonte (exceto talvez quando for apenas uma linha) e;
ABOLIR a forma de formatação de saída de programas como citação (mas citação pode ser usada para outras coisas obviamente).
Perguntas relacionadas no meta
E antes que alguém clique no botão de "fechar" e marcar essa pergunta como duplicata, eu estou ciente dessas perguntas:
Como devemos formatar perguntas e respostas? - A minha pergunta não é duplicata dessa outra porque a minha pergunta busca questionar uma prática vigente e propor uma mudança, e não apenas fornecer um guia geral de estilo (observe a tag faq nessa pergunta linkada).
Mensagens de erros ou Exceptions devem ser formatadas? - O exemplo que o OP desta pergunta deu não era um bom exemplo por ser demasiadamente simples e poder ser formatado igualmente de ambas as formas. Além disso, ele perguntou se o erro deve ser formatado, propondo ambas as formas citação e código-fonte. Já o foco desta minha pergunta não é se deve ser formatado e sim como deve ser formatado. Além disso, nessa pergunta linkada, o OP estava querendo uma orientação, enquanto que nessa minha pergunta, o propósito não é buscar orientação para mim, e sim questionar uma prática vigente no site e propor uma mudança.
editada 23/12/2017 às 21:48
9.67466 medalhas de prata1212 medalhas de bronze
Sou totalmente a favor da proposta. Pilha de erros como citação poluem visualmente a pergunta, dependendo do tamanho, até dificultam sua leitura. Eu sempre que possível formato como código e no máximo arrumo espaçamentos(no caso do Android e o logcat). Acho errado simplificar o erro, corre o risco de tirar ou atrapalhar o entendimento da origem do problema.
21/09/2016 às 15:54
É uma observação interessante e concordo. Eu acho que para casos simples onde é só a mensagem simples até poderia deixar a citação. Não gosto muito da ideia de usar formatação de código, seria legal ter uma outra forma, mas como não tem, vai ter que ser essa mesmo, é a única que resolve o problema.
21/09/2016 às 15:56
A minha resposta a isto é depende. Eu analiso sempre como fica melhor em cada caso e uso o que me parece melhor. Falta ai um caso em que a formatação em código é uma única linha com milhentos caracteres, ai eu prefiro mesmo citação.
21/09/2016 às 16:19
Eu costumo usar a citação para descrição de erro, devido ao problema mencionado pelo @JorgeB. em relação a formatação por código, entretanto, seria bem interessante se implementasse um novo recurso que permitisse formatar uma mensagem de erro.
21/09/2016 às 17:01
Já votei a favor, mas queria deixar explícito que também concordo. :)
21/09/2016 às 19:14
Não sei se você não editou a do exemplo 3 pela postagem ser antiga ou pelo simples fato do editor ser um moderador. Você pode (na verdade, deve) editar independente do ♦ no nome ou não. Isso ajuda a diminuir o nosso fardo do poder das ações vinculantes, que no caso da edição é a mesma que de qualquer usuário com ao menos 2k de rep ;-)
22/09/2016 às 12:08
@Math Deixei pra lá porque era uma postagem antiga.
22/09/2016 às 13:12
Também concordo com a proposta, iria facilitar muito, até porque nem todos andam com uma cópia do <!-- language: none --> por exemplo.
Possível solução: Citação de código
Se reunirmos as vantagens da citação com as do alinhamento correto, chegamos no "melhor dos dois mundos", sem nenhum prejuízo, usando recursos já existentes no editor/interpretador de Markdown.
Vantagens da "citação de código":
identifica os dados de saída de maneira diferente dos códigos-fonte;
não perde a informação relevante do alinhamento;
é sensato semanticamente;
simples de fazer, é só acrescentar dois caracteres no começo do bloco;
fica mais consistente visualmente com casos onde bastar só a citação (mensagens de uma linha só, comuns em SQL, PHP etc).
Você não consegue suprimir a colorização usando apenas <!-- language: lang-none -->, pois o encadeamento de blocos acaba desconsiderando a diretiva.
Neste caso, é necessário usar um <!-- language-all: lang-none --> para suprimir as cores, mas não pode esquecer de por <!-- language-all: lang-XXXX --> com a linguagem correta em seguida, caso ainda tenha algum bloco de código-fonte na sequência.
Formatar como código, normalmente (botão { } ou controlk)
acrescentar > apenas na 1a linha ( é o > com um espaço a mais depois).
O Meta não dá a melhor noção do universo, por causa das cores parecidas, então eu usei uma das postagens mencionadas como "cobaia", vejam aqui.
Vale lembrar que o uso da formatação de código em alguns casos atrapalha, gerando um scroll horizontal. Veja um caso com citação, em que basta uma olhadela para vermos a mensagem toda:
Warning: mysqli_fetch_array() expects parameter 1 to be mysqli_result, boolean given in C:\xampp\htdocs[testing]\login.php on line 16
Num caso desses, usando bloco de código, o leitor é obrigado a uma ação física a mais, tendo que "rolar" a mensagem para ver a linha e o source onde ocorreu o erro:
A citação seria sempre usada, mas com formatação de código embutida sempre que relevante;
normalmente pode se dizer que saídas estilo trace, com múltiplas linhas, geralmente se beneficiam do bloco de código dentro da citação;
não vem muito ao caso o número de linhas, mas sim o conteúdo. A aplicação do bloco de código é importante mesmo se for uma linha só, mas com a saída mostrando parte do código como strings com vários espaços;
finalmente, em casos onde fique evidente que o formato de código não tenha benefício, deixamos só a citação.
respondida 21/09/2016 às 21:30
Acho que é a melhor solução. Assim usa-se o recurso ideal e adicional o recurso necessário para resolver um problema nos casos que precisa da formatação. Mantém-se um padrão e deixa legível.
21/09/2016 às 21:37
Achei boa essa solução.
22/09/2016 às 1:46
Há um problema ainda: a coloração de sintaxe inadequada. Colocar o <!-- language: none --> antes da citação não funcionou para mim. Colocar dentro da citação antes do código também não funcionou para mim.
22/09/2016 às 13:31
Fica chatinho quando o stack vem no começo, mas tem solução sim: pt.stackoverflow.com/questions/140893/… - Mas de todos os problemas, acho que o stack coloridinho é o menos chato (e isso ja é um problema da mecânica do interpretador, eu diria).
22/09/2016 às 13:44
Ok, não sei o que pensar sobre o <!-- language-all: none --> no começo seguido de <!-- language-all: lang-java --> mais abaixo. O meu primeiro pensamento diz que isso é uma gambiarra muito frágil e muito propensa a erros. Mas o meu segundo pensamento diz que qualquer outra coisa também é igualmente frágil e igualmente propensa a erros, inclusive a situação como ela é hoje. Então, sei lá.
22/09/2016 às 13:47
@VictorStafusa Eu entendo o que você diz, ainda acho que a solução proposta tem o melhor "resultado final". De qq forma, vou fazer testes mais "intensivos" para ver até onde podemos melhorar o procedimento, e atualizo o post acima com instruções detalhadas. Acrescentarei sua boa observação numa lista de "Desvantagens:" com a devida solução (que por enquanto é o lang-all, mas pode ser que eu descubra alguma otimização, assim como descobri a citação de código) - Lembrando que fica "menos pior" quando o stack tá no final.
22/09/2016 às 13:48
Semanticamente é bom mesmo, mas visualmente acho poluído. O contexto não seria suficiente para as pessoas distinguirem códigos de stack traces e afins?
@bfavaretto o que muda é só a bordinha amarela (há uma certa poluição nisso? talvez). Eu acho que se adotarmos código pra tudo, caímos no problema do scroll chato em muitas situações, se mantivermos citação estraga os stack traces, e se for pra ficar "cada um por sí", é o que temos hoje. Quanto ao contexto, se você tem 1 stack e 1 código, acho que sim. Se tiver um stack trace no meio de 8 blocos de código, talvez complique. E se formos ver "caso a caso", vai do bom senso de cada um. Eu gosto do bom senso, só quis deixar uma solução pra quem num impasse, e me pareceu bom nos casos testados.
22/09/2016 às 14:38
@bfavaretto num mundo ideal eu gostaria de uma "citação de código" oficial, que fosse o código com fundo e bordinha igual a citação, mas com comportamento do bloco (e não 2 elementos aninhados). Mas a gente sabe que a rede não é muito flexivel nesse sentido. Por exemplo, linhas começadas por ] ...código...
22/09/2016 às 14:45
Concordo, mas duvido que implementem :P
A solução perfeita é ter uma marcador próprio.
@bigown e eu elegeria o ] ....... como simbolo da "citação monospace", por ser um símbolo fácil de lembrar e associar com código e com "alinhamento", e de improvável ocorrência "natural", como equivalente do > ......., pensei em uma proposta no big meta, mas tem coisa mais importante na fila faz tempo que não desencanta. Acho que seria muita energia para não ter retorno.
23/09/2016 às 18:05
O que alias já é a percepção geral de todos que acompanham a rede há um bom tempo. Onde a proposta fica esquecida em um canto ou há algum motivo para não fazer que a maioria discorda. Mas eles é que vão "gastar" pra fazer então a gente tem que aceitar como eles acharem melhor.
23/09/2016 às 18:09
Uma regra de CSS que reinterpretasse blockquote>pre>code já ajudava.
@bfavaretto eu acho que seria muito simples incorporar no markdown, mas eu entendo que a rede tem uma burocracia severa quando se trata de mexer com certas coisas (também conhecido como "não quero"). Precisaria de um ajustezinho no JS do highlighter tambem, mas nada "grave".