Guia de Estilo

Exemplo de Post

Python: Declarar a codificação dos fontes (encoding)

Tags: Python, encoding, latin-1, warning

Quando você coloca algum caractere acentuado no seu programa, por exemplo "á", um aviso é mostrado na execução:

sys:1: DeprecationWarning: Non-ASCII character '\xe1' in file foo.py on line 3, but no encoding declared; see http://www.python.org/peps/pep-0263.html for details

A codificação ASCII é o padrão para códigos fonte, então é preciso avisar o Python que seus fontes usam outra. Para o português é ISO-8859-1, ou seu similar mais curto latin-1. Basta colocar um comentário especial na primeira ou segunda linha do código:

# -*- coding: latin-1 -*-

Apesar de encorajado seu uso pela documentação, os -*- são desnecessários. Exemplo funcional:

# coding: latin-1
print "á"

Formato do Post

  • Título descritivo e Google-friendly, com o nome da linguagem no início
  • Linha com as tags da dica
  • Conteúdo da dica
    • Introdução (se julgar necessária)
    • Dica em si
      • Colocar trechos de código
      • Colocar o resultado dos comandos para facilitar o entendimento
    • Conclusão ou aviso (se julgar necessário)

Detalhes do Post

Título

  • Uma das partes MAIS importantes, que garante bom ranking nas pesquisas.
  • Tem que ser rico em palavras-chave que o usuário procuraria no Google para cair no seu post.
  • Sempre pense: se eu enfrentasse esse problema que meu post resolve, como eu procuraria a solução no Google? Quais palavras eu usaria?
  • Coloque o nome da linguagem no início, no formato "Linguagem: Título do post".
  • Quando o post falar de um único método/biblioteca/comando, é interessante ter seu nome no fim do título, entre parênteses, para ajudar nas pesquisas. Exemplo: "Java: Como ler, editar e salvar imagens (ImageIO)
  • Use capitalização de frase (como esta, somente a primeira letra em maiúscula). Não Use Title Caps. Exceções para palavras que normalmente são maiúsculas como Linux e OpenGL.
  • Prefira o infinitivo ao gerúndio. Ao invés de "Lendo linhas de um arquivo", use "Ler as linhas de um arquivo".
  • Lembre-se que é uma DICA e não um ARTIGO.
  • Seja técnico e prático, não poético.
Ruim Bom
Pau no OpenGL Segmentation fault em programas OpenGL com multi-threading
Errando no lugar certo Imprimindo mensagens de erro (stderr)
Deixando o código Javascript válido Validar Javascript dentro do XHTML com CDATA
Erro na linha de comando do shell Erro: Argument list too long
Formatando strings de um jeito esperto Formatar strings com dicionários (template)

Tags

  • O título pode não conseguir englobar tudo o que a dica fala. Use o campo Tags (logo abaixo da caixa de texto do post) para listar as palavras-chave relacionadas com a dica.
  • Pense quais palavras o leitor digitaria no Google.
  • Pode ter termos em inglês e português, o que for mais comum o uso.
  • Sempre coloque o nome da linguagem também nesta lista.
  • Não use formatação (negrito, itálico).
  • Capitalize as palavras normalmente: Python, PHP, string.
  • Exemplo: Tags: HTML, escape, escapar, html_escape, htmlspecialchars, htmlentities

Texto

  • Texto rápido e sem muita firula.
  • Sua vida pessoal não importa, tipo "Eu estava lavando o carro quando lembrei que a panela estava no fogo, e na corrida, lembrei do encoding do Python."
  • O texto deve passar profissionalismo. Não use gírias e regionalismos. Seja sóbrio, porém não necessariamente chato :)
  • Sempre que possível, mostre as mensagens de erro/warning no post. Quantas vezes você já não procurou no Google pela solução do problema copiando e colando a mensagem de warning? Então.
  • Sempre escreva pensando no Google. Que outras palavras você poderia colocar no meio do texto, que ajudariam o leitor a encontrar seu texto na Internet?
  • Se não for necessário, não explore TODOS os detalhes da dica. Deixe espaço para que os leitores também possam participar comentando! Neste exemplo, eu poderia ter dito que o espaço em branco depois dos dois-pontos é opcional, ou que é possível ter textos antes de depois da string mágica. Note que isso não significa deixar a dica pobre, mas sim KISS. Eventualmente algum leitor experiente vai adicionar essas informações.
  • Já tem uma dica complementar ou parecida no CODARE? Faça um link para ela!
  • Uma introdução ao problema (como neste caso explicar a origem e mostrar a mensagem de warning) é sempre bem-vinda para o leitor não cair de pára-quedas na tua dica. Você sabe bem do que ela se trata, mas o leitor não.
  • Evite parágrafos muito loooooooongos (chato de ler) e vários mini-parágrafos de meia linha (IRC kids). Use o bom senso.
  • O blog é em português, então sempre escreva os termos em português quando seu uso for comum. Coloque o termo em inglês entre parênteses para ajudar o Google a encontrar seu post. Como já temos os parênteses, não precisa usar itálico também. Exemplo: Para ligar a depuração (debug) você deve...
  • Evite o abuso de formatação. Dê destaques (negrito, itálico) apenas quando estritamente necessário para melhorar o entendimento da dica.
  • Não é necessário deixar em itálico palavras técnicas que todo programador está careca de saber: string, array, hash, ...

Trechos de código

  • Marque trechos de código com a tag <pre></pre>.
  • Pode deixar a tag PRE em uma linha só dela, para ficar mais legível: 
    Blablabla, veja o exemplo:

<pre>
foo = bar
print foo
</pre>

Blablabla...
  • Não ultrapasse 65 colunas. Tanto no blog quanto em revistas, livros e outras mídias, a largura não é generosa. Quebre linhas, faça funções, use atalhos (foo = FuncaoComNomeGigantesco).
  • Ao identar um trecho (sempre idente, sempre), use ESPAÇOS e não TABs, pois o tamanho do TAB varia nos navegadores :/ Use 3 ou 4 espaços para cada nível, o que preferir.
  • Use nomes curtos porém descritivos para variáveis e funções.
  • O trecho deve ser copiável & colável, pois é exatamente isso que o leitor vai fazer: colar e tentar rodar. Teste se o código funciona!
  • Se for mostrar uma linha de comando do Shell, use como prompt o $. Exemplo: $ ls /etc

Dicas de Português

  • Faça verificação ortográfica!
  • Numerais até nove são escritos por extenso: um, dois, três... De 10 em diante, coloca-se o número: 10, 11, 12...
  • Não use "veja exemplo abaixo", mas sim "veja o exemplo seguinte".
  • Faça verificação ortográfica!

Detalhes do WordPress

  • Ao mudar o título de um post, lembre-se de mudar também o "post slug".
  • Não é preciso usar as tags <P> para cada parágrafo, elas são inseridas automaticamente.
  • Não use o botão CODE para formatar trechos de código. Ao invés disso, englobe o trecho com as tags <pre> e </pre> "na mão".
  • Se precisar colocar &, < e > literais, use as entidades &amp; &lt; e &gt;.
  • Às vezes é preciso escapar a \ para que ela apareça, por exemplo use "\\n" para aparecer "\n". Mas confira nos Preview, parece que eles arrumaram esse bug.
  • Se for colocar um link para outro post do CODARE, use links relativos e não absolutos. Ao invés linkar o: https://codare.wordpress.com/2006/09/20/ler-linhas-de-um-arquivo-texto/ Use: /2006/09/20/ler-linhas-de-um-arquivo-texto/

Procedimento de postagem

  1. Entre com seu usuário e senha no WordPress.com.
  2. Entre no CODARE.
  3. Clique em "Write" ou "New Post".
  4. Escreva sua dica, seguindo as recomendações deste documento.
  5. Vá clicando em "Save and Continue Editing" para ver como o post está ficando.
  6. Deixe o "Post Status" como Draft mesmo.
  7. Ao terminar, aperte "Submit for Review".
  8. Então seu post entrará na fila e será publicado nos próximos dias.