Melhor documentação de transferência de projeto

Se você estiver trabalhando com composer , npm , bower ou qualquer outra dependência ou gerente de projeto que use JSON, aqui vai uma dica útil para aqueles que realmente desejam ou precisam documentar as coisas de uma maneira um pouco mais embutida ou alfabetizada.

Como você provavelmente já deve saber, JSON dificilmente permite comentários. Ele aceita apenas alguns comentários em certos lugares, mas no geral isso é desencorajado, pois este tópico do SO aborda a questão e com o que aprendi durante minha própria experimentação. As regras são uma maneira peculiar e pouco confiável de armazenar informações inline.

Isto é, até o surgimento do CSON. Adeus arquivos JSON e colchetes, Hello CSON e recuos. Devo admitir que o CSON também não é completamente intocado nesse sentido. Por um lado, ele tem todas as propriedades que a sintaxe CoffeeScript tem a respeito de objetos. Isso é:

• espaço em branco significativo
• colchetes implícitos para chaves e valores de objetos são permitidos

Para qualquer Pythoneer entre vocês: o primeiro é muito característico de seu idioma e marca registrada de longa data do idioma: omissão de colchetes e blocos de aninhamento por indentação (não foi o primeiro). A segunda viola uma regra do Zen do Python: “Explícito é melhor do que implícito” e, frequentemente, acho que, nesses casos, se refere a onde as coisas podem se tornar ambíguas, essas regras se estendem ao CoffeeScript 1: 1. Seria bom, como prática recomendada, informar-se antes de se tornar um aventureiro.

Provavelmente, sua melhor aposta é apenas aquecê-lo primeiro: porque somos preguiçosos e porque os scripts são mais precisos do que nós + garantimos os mesmos resultados se nada fora do comum for feito nos arquivos de origem – se ilegível, falhará de qualquer maneira .

Você precisará ter o Node.js instalado. Então faça por exemplo

npm i -g cson season

json2cson composer.json > composer.cson

Agora você tem uma nova cópia de um limpo . Você pode adicionar comentários de várias linhas ou de uma única linha agora, o que pode explicar a razão por trás de usar uma certa dependência necessária ou a motivação para deixar alguns para trás, ou por que eles deveriam pertencer ao dev. O que você disser..cson.json

Após o qual:

csonc composer.cson

composer validate && composer update

E voila: você tem a documentação embutida dos arquivos fonte do seu projeto: agora nenhum sucessor precisa adivinhar o motivo por trás de certas coisas: eles podem começar bem com a base de muitos aplicativos – as bibliotecas / pacotes que usa.

Uma grande desvantagem é que você teria que invocar uma solução se acontecer de você fazer muito:

npm i something --save

Você poderia então fazer outra viagem de ida e volta, de volta .jsonpara, .csonmas não teria nenhum comentário, então uma mesclagem de diff nesses arquivos seria necessária.

Dado todo esse problema, pode-se facilmente voltar às .jsonregras de simples ignorância e digitar comentários como, por exemplo,

% this is a new comment

E ter awk, grepou sedpuxar os para fora antes que você comece um processo automatizado. É igualmente trivial ter um composer.tplarquivo de modelo gerando um a composer.jsonpartir de apenas um script de shell simples usando ferramentas nix padrão (sem necessidade de npm).