Como documentar um design orientado a objetos no texto

5

Para o meu próximo projeto, estou procurando documentar meu projeto Orientado a Objetos em um texto simples antes de pular a arma para codificá-lo. Eu quero fazer isso por dois motivos.

  1. Eu quero pensar adequadamente no meu design e possivelmente revisá-lo várias vezes.
  2. Eu não decidi exatamente em qual idioma quero implementar meu projeto.

Estou procurando uma convenção para descrever meu design em texto simples, em vez de um diagrama UML. Eu gosto da conveniência do texto. Eu posso controlá-lo e colocá-lo facilmente em um blog ou wiki para compartilhá-lo.

Estou pensando em algo conciso, por exemplo como você pode codificar em Python. No entanto, quero que a representação seja independente do idioma. Eu olhei ao redor da internet mas não consegui encontrar nada. O mais próximo provavelmente seria como as propriedades e os métodos são definidos na caixa que representa uma classe em um modelo UML.

Atualização: Eu só queria esclarecer "no texto". Meu objetivo é poder delinear o modelo de objeto em um wiki do github. Eu imagino que seja uma espécie de código aberto além de código. Assim, posso criar uma página do Wiki por entidade e identificar os relacionamentos usando links e formatação, etc. No entanto, o que eu queria sugestões era como delinear a especificação de uma entidade em sua página.

    
por Danish 17.07.2012 / 20:31
fonte

3 respostas

6

Você pode escrever em HTML e usar hiperlinks para expressar relacionamentos entre diferentes classes. O problema, no entanto, é que você não pode ver links. Ao documentar um design, os relacionamentos são uma grande parte do que você está tentando explicar, por isso não será possível torná-los invisíveis.

Eu sugeriria esquecer textos simples. Use HTML, no mínimo, e não tenha medo de incluir imagens criadas em sua ferramenta gráfica / de desenho favorita. Eles podem não ser tão universais quanto o texto simples, mas você ainda poderá visualizá-los em qualquer navegador, e ainda assim poderá rastreá-los em um sistema de controle de versões.

    
por 17.07.2012 / 22:29
fonte
1

Tivemos um projeto enorme e eu documentei todas as funções do caixa usando Casos de Uso. Então, nós tivemos Depósito, Retirada, etc ... com cada um deles, vários processos locais, intermediários e backend foram processados. Em vários níveis, também tive acesso à mudança por segurança. Os casos de uso tornaram tudo isso muito claro e permitem que você documente não apenas o sistema, mas também os jogadores envolvidos. Ajuda a determinar em quais áreas você precisa criar bibliotecas de classes e que segurança diferente entra em ação.

Essa visão de alto nível torna muito fácil a) documentar o que está acontecendo - bem como - b) identificar possíveis sub-sistemas que você precisa projetar / construir. Vai, a longo prazo, tornar o seu próximo nível de design muito melhor (IMHO).

    
por 17.07.2012 / 22:24
fonte
0

As coisas mais próximas ao que você deseja são casos de uso. Estes representam uma representação textual dos requisitos, idéias e design da sua aplicação. Uma explicação simples pode ser encontrada aqui na wikipedia.

No entanto, para obter a melhor documentação, recomendo o livro Escrever casos de uso eficazes de Alistair Cockburn.

    
por 17.07.2012 / 21:48
fonte