Executando verificação de segurança...
Em resposta a Boas Práticas pra Documentos em Markdown
6
kht

Concordo com a ideia geral, principalmente sobre a questão de privilegiar texto puro. Emojis e outras firulas costumam ser ruído, e na minha opinião os casos em que fazem sentido costumam ser exceção.

Também gosto da ideia de minimizar dependências, mas acho que nem sempre é possível eliminá-las. Afinal, links são a base da internet, e acho que eles funcionam muito bem como complemento (tipo um "saiba mais"). Como tudo na vida, o problema não é o uso, e sim o mau uso (ex: usar somente links, delegando todo o conteúdo principal para eles). Já imagens, dependendo do conteúdo, não tem como evitar (diagramas ou gráficos com informações importantes, etc). De novo, o problema é o mau uso, como por exemplo imagens que não acrescentam nada ao conteúdo e que se retirar não faz falta nenhuma.

Sobre "boas práticas" em si, não gosto do termo, porque muita gente interpreta como uma regra imutável que sempre deve ser seguida. Isso é ainda mais prejudicial quando tem as palavras "sempre" ou "nunca" (ou "não faça isso", que pode ser interpretado como "nunca faça isso"). Eu vejo as tais "boas práticas" como recomendações, coisas que geralmente funcionam bem, mas que devem ser avaliadas caso a caso e adaptadas (ou até subvertidas) quando fizer sentido.

Por exemplo, discordo que não se deve usar tabelas. Novamente, o problema é o mau uso: tem casos que uma lista funciona bem melhor, mas tem casos que não. Por exemplo, se tivermos dados tabulares como a lista dos aeroportos mais movimentados do mundo, seria melhor uma tabela:

RankAirportLocationCountryCode (IATA/ICAO)Total passengersRank change% change
1United States Hartsfield–Jackson Atlanta International AirportAtlanta, GeorgiaUnited StatesATL/KATL104,653,4510↑ 11.7%
2United Arab Emirates Dubai International AirportGarhoud, Dubai, Dubai AUnited Arab EmiratesDXB/OMDB86,994,365↑ 3↑ 31.7%
3United States Dallas Fort Worth International AirportDallas–Fort Worth, TexasUnited StatesDFW/KDFW81,755,538↓ 1↑ 11.4%
4United Kingdom Heathrow AirportHillingdon, LondonUnited KingdomLHR/EGLL79,183,364↑ 4↑ 28.5%
5Japan Tokyo Haneda AirportŌta, TokyoJapanHND/RJTT78,719,302↑ 11↑ 55.1%

Ou uma lista?

  1. United States Hartsfield–Jackson Atlanta International Airport; Atlanta; Georgia, United States; ATL/KATL; 104,653,451; 0; ↑ 11.7%
  2. United Arab Emirates Dubai International Airport; Garhoud, Dubai, Dubai AUnited Arab Emirates; DXB/OMDB; 86,994,365; ↑ 3; ↑ 31.7%
  3. United States Dallas Fort Worth International Airport; Dallas–Fort Worth, Texas; United States; DFW/KDFW; 81,755,538; ↓ 1; ↑ 11.4%
  4. United Kingdom Heathrow Airport; Hillingdon, London; United Kingdom; LHR/EGLL; 79,183,364; ↑ 4; ↑ 28.5%
  5. Japan Tokyo Haneda Airport; Ōta, Tokyo; Japan; HND/RJTT; 78,719,302; ↑ 11; ↑ 55.1%

Concordo que tabelas são mais chatas de se mexer, e as ferramentas não ajudam muito (e nem sempre ela fica bem formatada, ainda mais se tiver muitas colunas, como foi o caso aqui; no celular então, fica terrível). Mas dizer que não se deve usá-las é exagero, existem casos de uso legítimos e situações em que elas são a ferramenta mais adequada. Creio que a "boa prática" deveria ser "pense nos tipos de dados que vc tem e qual a melhor forma de apresentá-los". Tem vezes que a melhor forma será uma tabela, tem vezes que não.

Por fim, também não gosto dessa limitação de 80 caracteres por linha, mas aí é gosto pessoal. Eu acho que isso fazia sentido antigamente, quando os monitores tinham esta limitação, mas hoje em dia eu configuro para ter pelo menos 120 caracteres. Se estou usando um monitor wide screen, uso até 160 sem pudor nenhum :-) Mas admito que é muito mais por gosto pessoal, sei que muita gente não se sente confortável com linhas tão compridas. E claro que se um projeto exigir, por exemplo, que as mensagens de commit tenham no máximo X caracteres por linha, eu vou respeitar a regra - mas aí não é porque a boa prática diz, e sim porque o chefe mandou :-)

Carregando publicação patrocinada...
3
kevinmarquesp

Poxa, então não consegui transmitir o que penso dessas "regras". No primeiro parágrafo mensionei que essa lista são convensões minhas, e no último tentei reforçar a ideia. Mas valeu ai pelo comentário e por compartilhar sua visão! E outra, também enxergo boas práticas desse jeito, porque se fossem regras se chamariam "regras". 😜

Sobre a questão das tabelas, eu tirei direto do repositório com os styleguides que me basiei, tive que listar aqui porque lidar com tabela – principalmente quando o editor não ajuda – é uma parada que me irrita bastante, então prefiro seguir o que disseram de usar listas no lugar. Mas assim, listas legíveis, só escrever os dados um do lado do outro é simplesmente pior que a tabela numa tela de celular, eu faria sua tabela assim:

  1. United States Hartsfield–Jackson Atlanta International Airport

    • Location: Atlanta, Georgia (United States)
    • Code (IATA/ICAO): ATL/KATL
    • Total passengers: 104,653,451
    • Rank change: 0
    • % change: ↑ 11.7%

  2. United Arab Emirates Dubai International Airport

    • Location: Garhoud, Dubai, Dubai AUnited Arab Emirates
    • Code (IATA/ICAO): DXB/OMDB
    • Total passengers: 86,994,365
    • Rank change: ↑ 3
    • % change: ↑ 31.7%

  3. United States Dallas Fort Worth International Airport

    • Location: Dallas–Fort Worth, Texas (United States)
    • Code (IATA/ICAO): DFW/KDFW
    • Total passengers: 81,755,538
    • Rank change: ↓ 1
    • % change: ↑ 11.4%

E sobre o limite de caracteres por linha, eu prefiro sempre limitar a 80 ou um pouco mais porque eu nunca sei que será a próxima pessoa que vai ler o que estou escrevendo, então meio 80 caracteres é meio que universalmente legível. Além disso, mesmo usando um monitor com resolução 1920x1080 – e com a DPI baixa, gosto de letrinha – ainda me beneficio com linhas curtas, porque quando eu abro uma janela com o terminal pra escrever e outras duas com o Firefox o texto continua legível, sem quebras de linhas estranhas, ou sem ele desaparecer na direita.

Eu sei que dá pra ativar/desativar o line wrap em todos os editores, em Vim isso é ainda mais conveniente, mas eu ainda prefiro respeitar esse limite pra caber o maximo de informação possível na tela.

2
kht
Autor
Autor

É, essa lista não ficou tão ruim quanto a minha. Tabela não ficou bom aqui, mas é por causa da forma como o site gerou o HTML. Se tivesse um scroll lateral sem truncar tanto as colunas, ficaria melhor.

Ainda sim, pra esse caso específico prefiro a tabela. Primeiro porque não preciso repetir "Location", "Code", etc pra cada item, e pelo menos pra mim, fica mais fácil achar as informações e comparar uns com os outros, já que os mesmos dados ficam na mesma coluna. Por exemplo, consigo ver o total de passageiros de todos em uma única "escaneada" pela respectiva coluna, o que é mais difícil com a lista.

Enfim, cai no que eu falei: dá pra achar soluções com listas e tabelas, e ambos possuem vantagens e desvantagens. Eu prefiro sugerir que se analise e pense sobre isso em vez de seguir regras rígidas do tipo "não use X".

2
kevinmarquesp

Sim, sim. Já até mudei algumas dessas palavrinhas nas minhas notas – acho não vou editar essa publicação porque você levantou uns tópicos super importantes, ai teus comentários não fariam muito sentido.

Essa é só a primeira parte de um artigo que vou fazer no futuro algum dia, só escrevi o material sobre a sintaxe de Markdown e afins. Na conclusão terá um tópico dedicado só pra invalidar tudo o que eu disse, pra dizer que cada caso é um caso e tudo tem vantagens e desvantagens como tu disse.

Valeu ai pela força!