80

Qual seria a melhor maneira de formatar nomes de produtos, marcas, linguagens de programação, entre outras palavras importantes do texto?

Tenho visto diversos usos, como o magic link da tag , ou php, php, php, php... e tenho a impressão de que nestes casos nenhuma formatação é de fato necessária, bastaria dizer "PHP", sem as aspas. Têm também casos de uso exagerado de marcas de citações e cabeçalhos.

Abaixo alguns exemplos. Nenhum deles é extremamente grave, vou passar a guardar os links quando encontrar casos mais gritantes.

Quando escrevo uma pergunta ou resposta, costumo usar formatação de código somente para trechos de código (ou nomes de variáveis, classes, etc.), itálico para termos estrangeiros ou com alguma ênfase, e negrito para algo que eu queira muito destacar (como uma frase-chave em uma resposta). Tags eu raramente uso.

Sou a favor de deixar o corpo das perguntas e respostas tão limpos quanto for possível. Assim, um trecho com formatação distinta realmente vai chamar a atenção, enquanto que o uso excessivo acaba comprometendo a fluidez do .

O que vocês acham?

Retorne para o índice da FAQ

0

4 Respostas 4

76

Guia de estilo para formatação de posts

Espero que todos contribuam e discutam nos comentários ou em chat (apague os comentários após uma discussão específica acabar e discuta outros assuntos em outro local). Aqui só cabe a discussão do estilo a ser adotado.

Isto é apenas um guia de estilo e não regras para serem impostas. Um guia de estilo PODE ser aplicado, mas não é obrigatório. Por outro lado, se ele for aplicado sem excessos e nem abusos, não há razão para desfazer o que foi feito. Queremos melhorar e não piorar. Aplicar o guia deve melhorar o entendimento da pergunta ou resposta.

Linha geral

  • Evite usar várias formatações em conjunto. Em muitos casos é desnecessário e dará um destaque exagerado. Mesmo que normalmente um texto deveria ser formatado com mais de estilo definido aqui, escolha o mais adequado e evite os demais.

  • Não altere por alterar. Toda alteração deve permitir uma legibilidade melhor. E não tente consertar um pequeno problema, mesmo ortográfico, que mal dá para perceber. Mas principalmente não vá consertar algo introduzindo um novo erro. Claro que ninguém vai ser expulso por causa disso, mas evite piorar o que não estava tão ruim. Não fique tentado a editar tudo o que vê que não está o ideal.

  • Quando houver um motivo bom o suficiente para não seguir alguma destas formas, uma outra forma poderá ser adotada no caso específico. Mas lembre-se que "porque gosta mais de um jeito" não é um bom motivo para trocar algo. O mais importante é ser legível e se possível da forma mais correta.

  • E o mais importante, mesmo que seja só formatação, não mexa em nada que você não conhece e não sabe se vai ficar melhor. Até para formatar é necessário conhecimento mínimo sobre o conteúdo.

Títulos e parágrafos

  • Para quebrar um texto em diferentes parágrafos, é necessário que haja uma linha em branco entre os dois parágrafos. Assim sendo, uma quebra de linha solitária não é suficiente, duas são necessárias.

  • Títulos podem ser definidos precedendo a linha correspondente por #. Para subtítulos, use ##.

Capitalização

  • Atenção ao case das palavras, especialmente em nomes próprios. Procure seguir os padrões adotados pelo fornecedor ou alguma fonte autoritativa. O mesmo vale para siglas que costumam ser em maiúsculas, mas cuidado que algumas palavras parecem siglas e não são. Alguns exemplos:

    Correto Errado
    PHP Php
    phpMyAdmin PHPMyAdmin ou variações
    Java JAVA
    Lua LUA
    BASIC Basic
    COBOL Cobol
    HTML Html ou html
    CSS css
    JavaScript ou JS Javascript ou Js
    jQuery jquery ou JQUERY ou Jquery ou JQuery
    MySQL MYSQL
    PostgreSQL postgres
    SOLID Solid
    JSON Json ou json
    XML xml
    .NET .Net
    ASP.NET asp.net ou ASP.Net
    etc...

    Abreviação não é problema desde que seja de conhecimento público.

  • A capitalização correta em qualquer local que exija capitalização, inclusive por norma gramatical, deve ser observada e é algo que vai além da formatação. Não é questão de ser "grammar nazi", só de fazer o certo.

Ênfases

  • Para deixar um trecho de texto em negrito, use ** antes e depois do texto. Por exemplo, o trecho **exemplo** fica assim: exemplo.

  • Para deixar um trecho de texto em itálico, use * antes e depois do texto. Por exemplo, o trecho *exemplo* fica assim: exemplo.

  • Para deixar um trecho de texto em negrito e em itálico, use *** antes e depois do texto. Por exemplo, o trecho ***exemplo*** fica assim: exemplo. Você também pode colocar negritos dentro de itálicos e vice-versa. Por exemplo, **texto*texto*texto** *texto**texto**texto* fica assim: textotextotexto textotextotexto.

  • Para deixar parte de uma palavra em negrito, use **, pois o __ não funciona. Por exemplo, **Pal**avra fica assim: Palavra. Mas __Pal__avra fica assim: __Pal__avra. O mesmo vale para itálico: *Pal*avra fica assim: Palavra. Mas _Pal_avra fica assim: _Pal_avra.

  • Texto riscado pode ser formatado com a tag <strike>. Por exemplo, o texto <strike>exemplo</strike> fica assim: exemplo.

  • Códigos-inline podem ser definidos com um ` antes e um depois. Por exemplo, o texto `exemplo` fica assim: exemplo.

  • Você também pode utilizar a tag <code> para texto com formatação que deva ser renderizado como código-inline. Por exemplo, <code>*itálico*</code> fica assim: itálico.

  • Se o trecho de código inline precisar de um espaço no início ou no fim, use a tag <code> em vez do `. Por exemplo, ` abc ` fica assim: abc (sem os espaços no início e fim), mas se você fizer <code> abc </code> fica assim: abc (com os espaços).

  • Não abuse de negrito e outras forma de destaque do texto. Se grande parte e principalmente partes irrelevantes do texto são destacadas, o que realmente importa acaba ficando sem o devido destaque.

  • Aspas podem ser usados para indicar algo com significado especial. Evite as aspas para citações ou para destacar algo. É comum as aspas serem usadas para indicar que o conteúdo não tem um sentido tão literal. Claro que aspas em código tem o tratamento normal que o código exige. Procure usar as aspas como forma de estilo do texto em si e não para formatar.

  • Evite títulos para ênfase. O título deve ser preferido sempre que for separar seções do texto. O negrito destaca, não serve para separar seções.

  • Não use `` (código-inline) para dar ênfase ou para formatar siglas ou nomes próprios. A formatação de código deve ser reservada somente para código e assemelhados.

  • Nomes próprios, especialmente de tecnologias, geralmente não precisam de ênfase, nem negrito, menos ainda da pré-formatação como código.

Tags

  • Não use tags nos títulos das perguntas. É redundante pois o site já é organizado através delas. Seu uso é justificado no título quando ocorre de maneira natural, p.ex.: "Posso usar jQuery para fazer tal coisa, ou tem que ser JavaScript puro?". Vide Quando se deve colocar o nome da linguagem no título?

  • Não use marcação de tags em nomes de tecnologias ou em palavras do texto a não ser que a vinculação a uma tag ajude a entender o texto (extremamente raro). Em geral o uso da tag torna o texto mais ilegível destacando partes irrelevantes e colocando a escrita de forma errada, já que a tag tem limitação na forma de escrita.

Citações

  • A marcação de quote (citação) > deve ser usado para citações de terceiros. Saídas de programas, mensagens de erro e textos que não são códigos podem ser considerados citações de terceiros.

  • A mesma marca é comumente usada para avisos e outros blocos de texto que mereçam algum destaque visual.

Código

  • Evite o uso de formatação de código para o que não é código.

  • Use a marcação de blocos de código com 4 espaços ou code fences (blocos delimitados por ``` ou ~~~) para formatar o código. Qualquer edição que torne o programa mais legível pode ser feita, mas não altere mais nada no código que não foi você que postou! Não altere estilo de código. Se o autor postou a chave na mesma linha do if, deixe ela lá.

  • Em caso de perguntas: se você achou um erro no programa, não mexa. Apenas avise o autor. Tirar o erro pode ser a solução do problema. E se achou um erro numa resposta, somente corrija se tiver absoluta certeza do que está fazendo.

  • Tente, sempre que possível, evitar o aparecimento de barras de rolagem horizontal no bloco de código. Isso é feito com quebras de linha no código para que a largura da linha não exceda a largura do post.

  • Use ` (pré-formatado) para marcar um pequeno bloco (na mesma linha) com formatação especial. Ele funciona muito como a marcação de código, portanto deve ser usado em contextos onde se espera um trecho de código, por exemplo: uma palavra chave, um operador, um símbolo (variável, função, campo de banco de dados, etc.), uma expressão de uma linguagem, um trecho de um statement, um termo usado dentro do programa ou que faz parte do domínio que está sendo discutido. Nomes de arquivos, caminhos (paths) e URLs também podem receber essa formatação.

  • Blocos de código que pertencem a um item de lista devem ser tabulados com 8 espaços.

  • Se depois do último item de uma lista vier um bloco de código independente, tabulado com 4 espaços, é necessário colocar um comentário HTML entre os dois para forçar a formatação correta do código, algo do tipo: <!-- br -->.

  • Blocos de códigos independentes que apareçam consecutivos podem ser separados com o uso de um comentário HTML do tipo <!-- --> para que eles não fiquem colados um no outro. Entretanto, em geral, a redação do post possivelmente ficaria melhor se houvesse um parágrafo de texto explicativo entre esses blocos, eliminando então a necessidade de usar-se o comentário HTML.

  • Utilize blocos de código no formato de snippet apenas quando se tratar de HTML, CSS, JavaScript e/ou SVG e que sejam executáveis no navegador. Para códigos em linguagens diversas dessas (em especial PHP, Java, C#, Python ou qualquer coisa que não vá executar no navegador), não utilize snippets. Caso vá utilizar os snippets, certifique-se de que seu código é completo e executável. O uso de jQuery nos snippets é permitido.

Imagens

  • Tente colocar a descrição da imagem substituindo o texto padrão, pois isso serve para identificação da imagem por sites como Google e Bing, e também para pessoas com deficiência visual (corresponde ao atributo alt).

     ![inserir a descrição da imagem aqui][1]
    
  • É possível linkar para a versão original da imagem, encapsulando o código da imagem com um link para ela mesma. Note o "ampliar" entre aspas, isso faz um tooltip do navegador sobre o link (corresponde ao atributo title):

     [![Visão geral do painel de ferramentas][1]][1]
    
     [1]: https://i.sstatic.net/AOQbD.png "ampliar"
    
  • Podemos mostrar versões menores da imagem original adicionando uma letra ao nome do arquivo, s para small e m para medium. Usando o link de imagem acima, a versão medium é https://i.sstatic.net/AOQbDm.png.

  • Como a qualidade das versões reduzidas do Imgur não é boa, uma alternativa é usar HTML:

     <img src="url-da-imagem" width="200" alt="descrição" title="Lorem ipsum" />
    
  • Relacionado: Como destacar imagens que tem um fundo branco?

Listas, links e separadores

  • Use itens onde realmente existem itens.
  • Dê preferência para link formatados. Ou seja, que o link seja aplicado em cima de um texto. Mas em alguns casos a própria URL pode funcionar bem (se ela é legível, curta, e ela própria indica para onde está indo). Force o link na URL com < >
  • Separe partes do texto com rule (linha horizontal) apenas se a separação é exigida. Assim como qualquer elemento. Não use para enfeitar.

HTML versus markdown

  • A maioria dos elementos de HTML não são necessários. Provavelmente os mais úteis são <sup></sup> e <sub></sub>. Prefira a forma de markdown do que HTML. Portanto evite usar <br/> quando dois ENTER funcionam melhor, e dois espaços em branco no final da linha forçam uma quebra de linha.

Tag <kbd>

  • Não se esqueça da marcação de teclado <kbd></kbd> quando está falando de teclas a serem acionadas ou em casos que o visual da tecla no local facilite a leitura. Não use para enfeitar. Por exemplo, <kbd>Ctrl + A</kbd> fica Ctrl + A.

Estrangeirismos e neologismos

  • Colocar em itálico palavras em inglês ou neologismos. Não precisa se preocupar que tudo esteja em itálico, mas ajuda diferenciar a palavra. Se o nome é próprio não precisa estar em itálico, mas também não estará errado se estiver. Evite, porque nome próprio não é estrangeirismo. Se é sigla, não precisa do itálico.

Certamente tem algumas formas melhores de formatar algumas coisas, esta primeira contribuição é apenas para iniciar. Algumas são proposições iniciais que podem e devem ser discutidas (algumas não são as mais adequadas). Deve haver uma forma melhor de organizar os itens também. Alguns exemplos reais de uso adequado e inadequado pode ajudar

10
  • 18
    E também é bom dar tempo pro autor editar. Uma coisa que eu noto muito é que os pobres editores compulsivos (aqueles que são perseguidos pelas malévolas panelas que fazem complô para botar o site em ordem) fazem é editar o post depois de 30 segundos que é postado, muitas vezes sem ao menos indicar ao autor o help do markdown, que seria muito mais educativo e respeitoso. Creio que sugerir ao autor uma melhoria seja melhor que por a mão no material alheio em quase todos os casos. Se não houver feedback, aí sim um edit é bem-vindo, creio eu.
    – Largato Mod
    Commented 6/05/2014 às 19:11
  • 12
    Uma boa recomendação sobre o tempo de espera é de dar pelo menos 5 minutos após a postagem. Esse é o grace period que o autor tem para fazer edições sem gerar uma nova revisão salva pelo sistema. Se alguém editar antes, vai-se a chance.
    – bfavaretto
    Commented 6/05/2014 às 19:18
  • 11
    @bfavaretto de fato, tem mais esse fator. De qualquer forma, acho muito importante postar o help do edit e dar a chance do pessoal aprender e melhorar (na filosofia do "ensine a pescar").
    – Largato Mod
    Commented 6/05/2014 às 19:18
  • 1
    Acho que um comentário pode ser feito a qualquer momento, talvez esse devesse ser a primeira ação antes da edição, sugerir que o próprio usuário edite sua questão, salvo quando o usuário não estiver familiarizado com os recursos de edição. É claro que para tudo existe exceção.
    – Paulo
    Commented 6/05/2014 às 22:12
  • @bigown Acho seria interessante publicar exemplos formatados, talvez fique visualmente mais fácil de entender. Não só listar como deveria ser formatado, mas dar exemplos formatados. Um exemplo mesmo seria a citação, colocar uma frase formatada acho que seria interessante.
    – Paulo
    Commented 6/05/2014 às 22:51
  • O uso de negrito nesta resposta me incomoda. Em um texto grande, ainda que sob a forma de itens, as expressões em negrito chamam atenção em demasia. Aliás, predileção por negrito é algo que me parece específico do Stack Overflow em português, mas talvez seja vício de percepção.
    – user7835
    Commented 7/05/2014 às 6:09
  • Muito bom e útil esse guia, esclareceu muita coisa para mim! Deveria estar linkado na ajuda do site sobre edição. É possível? Seria muito útil. Eu só discordo com a parte que diz que a sigla correta é ASP.Net. No próprio site da Microsoft é fácil verificar que o termo correto é ASP.NET: asp.net. Commented 16/10/2018 às 15:02
  • @PedroGaspar Não dá para colocar lá, mas posso colocar em destaque depois das eleições. Editei.
    – Maniero Mod
    Commented 16/10/2018 às 15:05
  • @Maniero, por coincidência, acabei de achar uma página da ajuda (pt.stackoverflow.com/help/privileges/comment) que contém um link para o Meta: "Consulte Como funcionam as respostas aos comentários?"! Então será que dá? Commented 16/10/2018 às 17:12
  • @Maniero, agora que vi que provavelmente é porque a página original da ajuda (stackoverflow.com/help/privileges/comment) já contém também um link para uma pergunta do Meta. Commented 16/10/2018 às 17:26
20

Esses dias esbarrei na web com um exemplo de como NÃO se deve formatar um texto (obra do Supremo Tribunal Federal brasileiro, por algum motivo juristas gostam desses excessos):

inserir a descrição da imagem aqui

3
  • 4
    Não consigo entender porque, na terceira linha, o e está em negrito e sublinhado.
    – emanuelsn
    Commented 14/07/2015 às 11:59
  • 12
    @emanuelsn é por que eles não leram as nossas instruções ;-)
    – Math Mod
    Commented 14/07/2015 às 14:32
  • 5
    @emanuelsn é porque eles não são programadores e não entendem bem que E é E e ponto, precisa ser os dois, então precisa ressaltar para a anta que vai ler :D
    – Maniero Mod
    Commented 14/07/2015 às 15:17
18

Concordo plenamente com o @bfavaretto que:

(...) enquanto que o uso excessivo acaba comprometendo a fluidez do

Mas ao mesmo tempo, esse é um dos casos em que decidir uma regra formal vai causar mais prejuízo do que benefício. Definir, manter e principalmente aplicar uma regra dessas é trabalhoso, cansativo e interminável. A idéia de um guia, proposta nos comentários da resposta do @Strokes pode ser um bom meio termo.

O guia não serviria como "legislação", mas sua adoção voluntaria por diversos usuários certamente influenciaria o resto da comunidade, e ele se tornaria o padrão de facto. A comunidade atingiria uma unificação "por osmose", e não por um esforço ativo que traria pouco retorno.

9

Eu uso fóruns há anos na internet e sou a favor de títulos esclarecedores - até fiquei surpreso em ver um meu na lista. Não acho que seja necessário uma formatação padrão de como fazer a pergunta/descrição do problema desde que estes estejam claros, ou seja, título extremamente resumido e então o "desenrolar" da história, algo direto.

Se as coisas tornarem-se muito burocráticas só vai afastar pessoas interessadas em participar - veja bem, sou contra o total descaso mas acho que burocracia demais atrapalha. E concordo que não há necessidade de formatar o nome de linguagens, ou abusar de formatações desnecessárias como comentado pelo autor.

11
  • 1
    Minha discussão não é sobre os títulos, embora no caso da sua pergunta eu ache que a lista de ferramentas no final do título deveria estar no corpo da pergunta, e/ou nas tags. Usei sua pergunta como exemplo por causa da formatação introduzida nas edições.
    – bfavaretto
    Commented 18/03/2014 às 13:19
  • 3
    Esclarecendo, os sites da rede Stack Exchange não são fóruns (no sentido clássico da internet). São sites de Pergunta e Resposta onde o ruído ("olá!", "eu também!", "tag, tag, tag, resto do título", "pergunta duplicada pela enésima vez") não tem vez. O sistema de Tags está aí pra classificar o conteúdo e os especialistas/entusiastas que seguem o site filtram seus tópicos de interesse usando esse sistema. Confira o guia tour e a central de ajuda para mais detalhes.
    – brasofilo
    Commented 18/03/2014 às 13:26
  • 2
    Primeiramente desculpe-me se fiz parecer algo pessoal, não foi a intenção. Não havia entendido que havia se referido às edições que fizeram na minha pergunta, também achei algumas desnecessárias. A minha justificativa para as ferramentas no final da pergunta - também concordo que devam estar no meio da pergunta - foi que não consegui incluir todas como tags pois não possuo reputação suficiente para adicionar novas tags. E sim, tenho conhecimento da diferença entra a rede e os fóruns "tradicionais", só quis dar a entender que tenho experiência e tento seguir uma conduta positiva.
    – Matt S
    Commented 18/03/2014 às 14:02
  • 3
    Eu concordo com o que você diz sobre evitar tornar as coisas muito burocráticas. Não acho que precise haver regras rígidas sobre formatação, mas realmente me incomodo com o tipo de coisa que tem sido introduzida, principalmente em edições. Meu medo é que isso vire uma "praga" :)
    – bfavaretto
    Commented 18/03/2014 às 14:22
  • 1
    Quem sabe um documento "Como formatar" na Central de Ajuda. Eu também tenho visto algumas coisas estranhas na fila de revisão. Com um link "oficial" de ajuda poderíamos direcionar novos usuários à adotar as convenções de formatação do site. Commented 18/03/2014 às 15:10
  • Na verdade mesmo no SOE, sempre achei que a referência principal sobre "Como Perguntar" deveria linkar diretamente a página sobre markdown e alguma espécie de convenção (ou ao menos um guia de boas práticas sobre formatação). Commented 18/03/2014 às 15:16
  • 1
    @AnthonyAccioly A página sobre markdown foi a primeira coisa que olhei antes de postar esta discussão. Mas ela não discute quando usar cada tipo de formatação, somente explica a sintaxe do markdown. Esse conteúdo cairia bem no FAQ da Comunidade. Tá a fim de esboçar algo lá?
    – bfavaretto
    Commented 18/03/2014 às 15:38
  • Sim, podemos. Apesar de eu não ter ideia de como descrever a convenção para alguns construtores do tipo listas (acho que muitas vezes eu abuso desse tipo de construção também hehehe). Marcamos essa pergunta aqui como Community Wiki ou criamos uma nova? Commented 18/03/2014 às 15:52
  • Boa pergunta. Não dá para marcar a pergunta como CW, tem de sinalizar pro Gabe fazer isso. Pensando bem, se é para transformar esta aqui em FAQ, melhor esperar mais opiniões antes, @AnthonyAccioly.
    – bfavaretto
    Commented 18/03/2014 às 15:53
  • Ok, fico no aguardo :). Commented 18/03/2014 às 16:33
  • Concordo, o importante é a leitura clara e intuitiva, que faça os usuários baterem o olho e logo sacarem tudo de cara, é esse o objetivo que um texto informativo tem, uma pergunta, uma resposta, se você logo por o olho nos pontos diferenciais você tem uma leitura extremamente melhor e mais rápida. Commented 22/03/2014 às 1:18

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .