Quando deveria “deveria” ser usado na documentação? [duplicado]

5

Eu estava lendo o link e perguntando sobre algumas questões de estilo de documentação. Um deles foi o uso da palavra "deveria".

Por exemplo:

This method should be overridden when implementing a new Layer class. By default it raises NotImplementedError.

Esse é um lugar onde "deveria" deveria ser usado? Parece-me que o seguinte seria melhor:

This method has to be overridden when implementing a new Layer class. Otherwise, it raises NotImplementedError.

Existe algum guia de estilo sobre essas questões de estilo de documentação independente de linguagem? (por exemplo, se uma documentação fosse escrita em voz passiva ou com "você" ou "o desenvolvedor" seria outra pergunta)

Por favor, note que eu não estou escrevendo requisitos. Esta é uma pergunta sobre documentação de uma biblioteca.

    
por Martin Thoma 03.06.2015 / 21:40
fonte

3 respostas

6

Desde que eu li RFC 2119 , comecei a colocar uma referência a ele nas especificações - até a documentação do código . Um comentário como o seguinte, em algum lugar na documentação, ajuda a definir o padrão de interpretação.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (https://www.ietf.org/rfc/rfc2119.txt)

É um RFC bem pequeno e fácil de entender e você só precisa lê-lo uma vez.

    
por 03.06.2015 / 22:29
fonte
0

O termo "deve" tende a ser reservado para situações completamente em preto e branco onde você realmente não tem outra opção a não ser fazer algo de uma maneira específica, ou então a falha é inescapável.

A pessoa que escreve a documentação não pode escrever "deve" se for possível para alguém, em algumas circunstâncias, não importa o quão artificial, provar que tecnicamente, a questão que está sendo discutida não é uma necessidade absoluta.

Em outras palavras, suponho que deve ser bastante fácil para alguém implementar uma nova "Classe de Camada" sem substituir o método que lança NotImplementedError e, em seguida, proceder à instanciação dessa classe, invocar alguns de seus métodos ao fazer Certifique-se de não chamar o método problemático e, em seguida, vá "voila! Não foi necessário sobrescrever esse método depois de tudo!"

Naturalmente, toda essa discussão pode ser uma tentativa de ler muito a palavra escrita da documentação. Talvez a pessoa que escreveu a documentação simplesmente não tenha se empenhado em usar a palavra mais precisa possível da língua inglesa, de modo que eles simplesmente escreveram "deveria" como sinônimo de "deve".

    
por 03.06.2015 / 22:20
fonte
0

RFC2119 foi mencionado. De acordo com a RFC2119, "deve" significa: pode haver, talvez, em algumas circunstâncias, razões pelas quais você não seguiria a exigência, mas você deve pensar seriamente sobre isso e considerar todas as conseqüências.

Isso parece descrever a situação muito bem.

    
por 04.06.2015 / 00:23
fonte