Existem práticas comuns para comentar as expressões regulares: comentários embutidos que referem parte diferente do RegEx ou comentário geral para todas as expressões?
documentation
coding-style
comments
m0nhawk
fonte
fonte
Respostas:
A meu ver, uma boa prática é declarar concisamente nos comentários qual é a idéia geral da expressão regular. Isso poupa a outros desenvolvedores (ou às vezes a você mesmo) o trabalho de copiar e colar a regex em um analisador como o RegExr , apenas para entender o que ele faz.
fonte
Essa é uma resposta específica do idioma, mas nenhum idioma é declarado na pergunta.
O livro "Dive Into Python" sugere a implementação de comentários usando expressões regulares verbais :
Exemplo:
Fonte e mais detalhes aqui
Esse método tem uma pequena desvantagem de que o responsável pela chamada deve saber que o padrão está escrito em um formato detalhado e chamá-lo de acordo.
fonte
re.compile
no ponto em que define seu padrão e armazenar apenas o objeto resultante. Dessa forma, os sinalizadores de compilação do padrão (inclusivere.VERBOSE
) não precisam ser separados do próprio padrão.#
se estou usando a bandeira detalhada? A propósito: os links de origem parecem estar inoperantes.#
pode ser correspondido literalmente, quando dentro de uma classe de caracteres:[#]
(fonte: docs.python.org/3/library/re.html#re.X )Normalmente, escreverei uma regex e não explicarei as partes individuais da regex, mas qual é seu objetivo. É isso que e por quê. É um pouco como perguntar "Como devem ser meus comentários?" ao qual alguém diria " Não escreva o que o código está fazendo, escreva por que o código está fazendo o que faz "
A menos que você esteja tentando ensinar alguém sobre regexes por meio de comentários no código, não acho que seja possível explicar o que cada peça individual fará. Ao trabalhar com outros programadores, você pode assumir com segurança que alguém saberia algo como expressões regulares globais.
fonte
Eu acho que depende realmente de como você está montando o regex. De um modo geral, acho que seria uma má idéia colocar comentários dentro da própria cadeia de caracteres de regex (não é possível na maioria dos cenários, pelo que sei). Se você realmente precisar comentar partes específicas de uma expressão regular (você está tentando ensinar alguém?), Divida cada pedaço em seqüências de caracteres separadas em suas próprias linhas e comente cada linha usando o processo normal de comentários para sua linguagem de programação. Caso contrário, a resposta de pleinolijf é muito boa.
exemplo:
fonte
Normalmente, defino uma constante de sequência cujo nome descreve o objetivo geral da expressão regular.
Por exemplo:
Você pode adicionar um comentário acima dessa constante para fornecer uma descrição, mas geralmente o nome da constante em si deve ser suficiente.
fonte
Em alguns cenários, os desenvolvedores podem estar usando expressões regulares para corresponder ao texto fora de seu domínio típico. Os desenvolvedores originais podem ter passado por muitas iterações, capturando vários casos extremos que podem ter sido descobertos apenas por esse processo iterativo. Portanto, os desenvolvedores subseqüentes podem não estar cientes de muitos dos casos extremos com os quais os desenvolvedores originais lidaram, mesmo que estejam cientes do caso geral.
Em casos como esses, pode valer a pena documentar exemplos das variações. A localização desta documentação pode variar dependendo da quantidade (por exemplo, não necessariamente no código).
Uma maneira de abordar isso é assumir que futuros desenvolvedores terão apenas conhecimento básico, como o funcionamento das expressões regulares, mas nenhum conhecimento que você (1) tenha antes do desenvolvimento das expressões regulares que não seriam necessariamente conhecidas pelo usuário. desenvolvedores futuros ou (2) conhecimento que você adquiriu durante o desenvolvimento (por exemplo, casos extremos que foram descobertos).
Por exemplo, se durante o desenvolvimento você disser algo como "Ah, eu não sabia que X poderia assumir esse formato", vale a pena documentar isso (e talvez a parte do regex que lida com essa variação).
fonte
Os comentários devem adicionar informações úteis que não são óbvias no código.
Existem poucos aplicativos que precisam de todos os ciclos finais, se você estiver combinando conjuntos de dados maciços de padrões, talvez haja uma maneira melhor, talvez não, mas, na maioria das vezes, o tempo de execução extra não é tão importante.
E lembre-se de que a próxima pessoa a encontrar seu código e corrigir um bug pode ser você em seis meses e não há como você se lembrar do que deveria fazer.
fonte
Extraia o RegEx em uma classe separada em um com um nome significativo. Depois, documentava o código com testes automatizados.
Isso garantirá
Naturalmente, sua classe pode hospedar várias regexs.
fonte