As palavras "código de auto-documentação" é outra maneira de dizer "código legível". Por si só, não substituirá esta documentação ou bons comentários , mas com ou sem eles definitivamente tornará sua vida e a vida de seus colegas mais fáceis.

Vejamos alguns princípios importantes para a criação de código de auto-documentação.

Não use "números mágicos"

Diga-me, o que essa linha significa?

if (students.length > 23) { 

Verifica se há mais estudantes do que 23 anos? E o que isso significa? Por que exatamente 23, e não, digamos, 24?

Um número mágico é um número sem contexto. Você precisará gastar tempo e esforço para entender esse contexto. Livre-se do trabalho desnecessário, imediatamente dê explicitamente ao número a designação:

 const maxClassSize = 23; if (students.length > maxClassSize) { 

Tente ler o código agora. Verificamos não "se há mais alunos do que 23", mas "se há mais alunos do que a classe acomoda".

Use nomes claros para variáveis

Eu não sei por que, mas antes eu estava constantemente com medo de fazer nomes de variáveis ​​longos. O que foi estúpido da minha parte, pois rStuNms e fStuNms são terríveis em comparação com r awStudentNames e filterStudentNames .

Os últimos ainda parecem longos? Então pense sobre isso: após 2 semanas de férias e trabalhando com outro código, você esquecerá boa parte das abreviações. Ou seja, a capacidade de ler nomes de variáveis ​​em movimento é a capacidade de ler código em tempo real:

 const fStuNms = stus.map(s => sn) //    const filteredStudentNames = students.map(student => { return student.name; }); 

Outra boa dica é usar convenções (convenções de nomenclatura). Se a variável for booleana, inicie seu nome com is ou has ( isEnrolled: true ). Se a variável for uma matriz, use o plural ( alunos ). Muitos números devem começar com mínimo ou máximo . E os nomes das funções devem conter um verbo, por exemplo, createSchedule ou updateNickname . Falando de recursos ...

Escreva pequenas funções nomeadas

Variáveis ​​não são a única maneira de ler código. Como jovem programador, usei funções apenas para evitar duplicação de código . A verdadeira revelação para mim foi que, antes de tudo, faz sentido criar funções para descrever o que está acontecendo .

Reserve alguns segundos para analisar este código e dizer o que ele faz:

 const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); }; 

Agora faça o mesmo para o código:

 const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); }; 

Parece que há mais personagens, mas quanto mais legível, certo? Tudo o que era necessário era distribuir as operações lógicas em pequenas funções nomeadas. Além disso, as próprias funções pequenas não são necessárias para leitura na maioria das situações - esses são detalhes de implementação. Para entender o código, basta olhar para a função superior, que consiste em uma cadeia de eventos facilmente compreendidos.

Além disso - um pouco mais tarde, você perceberá que essas funções pequenas são muito fáceis de reutilizar. A reutilização é uma consequência da legibilidade aprimorada, e não vice-versa.

Adicione descrições de teste úteis

Provavelmente os menos comentados são testes auto-documentados, mas em vão.

Digamos que temos uma função como esta:

 const getDailySchedule = (student, dayOfWeek) => { 

Imagine que ele contém muitas operações diferentes: recebe um cronograma para um mês; se hoje é dia de folga, retorna uma matriz vazia; se o aluno estiver matriculado em aulas adicionais, adicione-os no final do dia etc. Em geral, você entendeu a idéia: a função é complexa e seria bom anotar o algoritmo de seu trabalho em algum lugar em palavras simples.

Tentar encaixá-lo em um comentário é uma péssima idéia: um comentário se tornará obsoleto e não o fato de que será corrigido a tempo. Você sabe onde a gravação do algoritmo de operação é apropriada? Nos testes:

 describe('getDailySchedule ', () => { it("   ", () => { it('  ,   ', () => { it('     ', () => { 

Essa é a maneira mais elegante de comentar o código sem comentar no código.

Conclusão: a legibilidade é mais importante que a inteligência

Qualquer um pode escrever um código que seja compreensível para si mesmo; um bom desenvolvedor escreve um código que é compreensível para os outros . Raramente é algo importante criado por uma única pessoa, o que significa que mais cedo ou mais tarde outras pessoas lerão seu código. Porém, mesmo se você tiver certeza de que somente você se debruçará sobre algum código, considere que você, hoje e você, em um mês, são pessoas diferentes em termos da capacidade de se lembrar desse código.