Skip to main content
adicionou 119 caracteres ao conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil

Documentar é convenção, as regras são adotadas de acordo com o jeito que a pessoa/equipe determina que deva ser. Algumas ferramentas que ajudam documentar só trabalham assimde uma determinada forma. Então pode fazer de um jeito ou de outro, só deve ser consistente e sempre fazer igual.

Nas documentações públicas é comum escolher entre:

  • que não se documentedocumentar o que veio herdado
  • que documentedocumentar só o que foi sobreposto, o que não acontece em campos
  • que documentedocumentar tudo que está disponível na classe

Tudo isso para membros públicos. O que eu nunca vi é documentar os membros privados de uma classe, porque o que é privado é detalhe de implementação, portanto não deve ser documentado para as pessoas usarem. O que é documentação gera um contrato, e se escolheu algo privado é porque quer liberdade para mudar no futuro, portanto não pode gerar um contrato para as pessoas usarem. 

O exemplo citado é de campos privados, portanto não deve estar na documentação de ambas as classes. Se é privado sequer você tem acesso direto na subclasse, ao contrário do que afirma a pergunta.

Note que estou usando o termo camposestou usando o termo campos porque provavelmente vai documentar um código feito em alguma linguagem de programação, atributo só é usado em UML, que é algo que não tem utilidade prática. E de certa forma é uma documentação, que fixafica defasada facilmente oue/ou gera dois trabalhos. E ela escolheu que não terá acesso aos "atributos" de outra classe, pelo menos não privativamente, como pode ser visto na pergunta.

Não entrei na questão de erros de design porque isso não é o foco da pergunta.

Documentar é convenção, as regras são adotadas de acordo com o jeito que a pessoa/equipe determina que deva ser. Algumas ferramentas que ajudam documentar só trabalham assim. Então pode fazer de um jeito ou de outro, só deve ser consistente e sempre fazer igual.

Nas documentações públicas é comum:

  • que não se documente o que veio herdado
  • que documente só o que foi sobreposto, o que não acontece em campos
  • que documente tudo que está disponível na classe

Tudo isso para membros públicos. O que eu nunca vi é documentar os membros privados de uma classe, porque o que é privado é detalhe de implementação, portanto não deve ser documentado para as pessoas usarem. O que é documentação gera um contrato, e se escolheu algo privado é porque quer liberdade para mudar no futuro, portanto não pode gerar um contrato para as pessoas usarem. O exemplo citado é de campos privados, portanto não deve estar na documentação de ambas as classes. Se é privado sequer você tem acesso direto na subclasse, ao contrário do que afirma a pergunta.

Note que estou usando o termo campos porque provavelmente vai documentar um código feito em alguma linguagem de programação, atributo só é usado em UML, que é algo que não tem utilidade prática. E de certa forma é uma documentação, que fixa defasada facilmente ou gera dois trabalhos. E ela escolheu que não terá acesso aos "atributos" de outra classe, pelo menos não privativamente.

Não entrei na questão de erros de design porque isso não é o foco da pergunta.

Documentar é convenção, as regras são adotadas de acordo com o jeito que a pessoa/equipe determina que deva ser. Algumas ferramentas que ajudam documentar só trabalham de uma determinada forma. Então pode fazer de um jeito ou de outro, só deve ser consistente e sempre fazer igual.

Nas documentações públicas é comum escolher entre:

  • não documentar o que veio herdado
  • documentar só o que foi sobreposto, o que não acontece em campos
  • documentar tudo que está disponível na classe

Tudo isso para membros públicos. O que eu nunca vi é documentar os membros privados de uma classe, porque o que é privado é detalhe de implementação, portanto não deve ser documentado para as pessoas usarem. O que é documentação gera um contrato, e se escolheu algo privado é porque quer liberdade para mudar no futuro, portanto não pode gerar um contrato para as pessoas usarem. 

O exemplo citado é de campos privados, portanto não deve estar na documentação de ambas as classes. Se é privado sequer você tem acesso direto na subclasse, ao contrário do que afirma a pergunta.

Note que estou usando o termo campos porque provavelmente vai documentar um código feito em alguma linguagem de programação, atributo só é usado em UML, que é algo que não tem utilidade prática. E de certa forma é uma documentação, que fica defasada facilmente e/ou gera dois trabalhos. E ela escolheu que não terá acesso aos "atributos" de outra classe, pelo menos não privativamente, como pode ser visto na pergunta.

Não entrei na questão de erros de design porque isso não é o foco da pergunta.

Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil

Documentar é convenção, as regras são adotadas de acordo com o jeito que a pessoa/equipe determina que deva ser. Algumas ferramentas que ajudam documentar só trabalham assim. Então pode fazer de um jeito ou de outro, só deve ser consistente e sempre fazer igual.

Nas documentações públicas é comum:

  • que não se documente o que veio herdado
  • que documente só o que foi sobreposto, o que não acontece em campos
  • que documente tudo que está disponível na classe

Tudo isso para membros públicos. O que eu nunca vi é documentar os membros privados de uma classe, porque o que é privado é detalhe de implementação, portanto não deve ser documentado para as pessoas usarem. O que é documentação gera um contrato, e se escolheu algo privado é porque quer liberdade para mudar no futuro, portanto não pode gerar um contrato para as pessoas usarem. O exemplo citado é de campos privados, portanto não deve estar na documentação de ambas as classes. Se é privado sequer você tem acesso direto na subclasse, ao contrário do que afirma a pergunta.

Note que estou usando o termo campos porque provavelmente vai documentar um código feito em alguma linguagem de programação, atributo só é usado em UML, que é algo que não tem utilidade prática. E de certa forma é uma documentação, que fixa defasada facilmente ou gera dois trabalhos. E ela escolheu que não terá acesso aos "atributos" de outra classe, pelo menos não privativamente.

Não entrei na questão de erros de design porque isso não é o foco da pergunta.