c







Documentação Técnica de Sistemas
Engenharia de Software

{
 


  
 
x 

 ecessidade ou preciosismo? A documentação

de software, mesmo sendo o carma de qualquer
desenvolvedor, é extremamente necessária e
auxilia na redução de horas preciosas na
correção de problemas. este primeiro
momento, vamos ver o que é a documentação
de um sistema, suas partes principais e também
as ferramentas que auxiliam desenvolvedores a
fazer desta uma tarefa menos maçante.
x 


ara muitos desenvolvedores, a criação de

documentação técnica é a parte mais
aterrorizante para se enfrentar em todo o
processo de criação de um software, seja pela
necessidade de escrever várias e várias
páginas de texto, gráficos e desenhos ou ainda
pela necessidade de largar aquilo que se
aprendeu (programar) para fazer aquilo que não
sabe bem (redigir).
 .
x 

 Entretanto a documentação é parte integrante

de qualquer sistema ou programa criado. Arrisco
a dizer inclusive que a documentação é tão
importante (ou mais) que as questões de
segurança pois sem a devida documentação,
^
 e pontos vulneráveis no sistema demoram
a ser encontrados e corrigidos, permitindo assim
que os ataques continuem levando à falência
múltipla do sistema e, conseqüentemente, de
seu usuário.
x 

 ormalmente, em grandes corporações existem

pessoas e/ou equipes voltadas única e
exclusivamente para a criação de
documentação, sendo que o desenvolvedor fica
restrito à codificação e comentários de seu
código. Já no mundo "real", esta atividade é
realizada pelo próprio desenvolvedor e
demanda um bom conjunto de horas para
planejar e criar cada uma de suas partes a fim
de atender minimamente as necessidades do
produto desenvolvido.
x 

 Então, como não é possível evitar a criação da

documentação técnica, vamos tentar amenizar
um pouco sua horrível aparência usando
ferramentas que auxiliam na tarefa de domar o
monstro. Mas, antes disso, uma pequena
apresentação do que é a documentação em si.
?

  
 A documentação de um software é composta
por várias partes diferentes que abrangem todo
o sistema e pode ser dividida em dois grandes
grupos: documentação técnica e documentação
de uso. A primeira é voltada ao desenvolvedor
ou pessoa de TI e compreende principalmente
dicionários e modelos de dados, fluxogramas de
processos e regras de negócios, dicionários de
funções e comentários de código.
?

  
 Já a documentação de uso é voltada tanto para
o usuário final quanto para o administrador do
sistema e, comumente, é formada por apostilas
ou manuais que apresentam como o software
deve ser usado, o que esperar dele e como
receber as informações que se deseja.
?

  
 A primeira parte (técnica) é, para o
desenvolvedor, a mais simples pois,
literalmente, descreve seu trabalho e também é
utilizada pelo mesmo como ferramenta para o
desenvolvimento de um bom código. Já a
segunda costuma ser um martírio pois a
redação de manuais, inserção de 
,
desenhos e outros elementos gráficos não é
aquilo que podemos considerar como  deste
profissional (são raros os que possuem).
?

  
 Ambas podem ser criadas em vários formatos
de visualização tais como páginas HTML,
documentos
DF, apresentações, vídeos ou
ainda arquivos texto. A forma de apresentação
não importa. O importante é saber que para
cada tarefa existe uma ferramenta certa,
inclusive para a documentação de sistemas em
qualquer nível de complexidade ou necessidade
e que precisa ser feita, de uma forma ou de
outra.
ë  


 Aproveitando a divisão da documentação

em duas grandes áreas, vamos conhecer
suas partes e algumas ferramentas que
ajudam e/ou facilitam aqueles que tem
pela frente a tarefa de gerar
documentação de sistemas.
©  

 Modelos de dados são aquelas folhas com

várias caixinhas das tabelas de um banco
de dados interligadas e que muitas vezes
somente são utilizadas para decoração de
escritórios. Mas longe de ser um quadro
ou pôster, o modelo de dados reflete de
uma forma gráfica (e lógica) a base de
dados de um sistema, seus
relacionamentos, entidades, chaves e
tudo aquilo que é referente aos dados em
si.
©  

 Este modelo, junto com o dicionário de

dados, é peça fundamental para o
desenvolvimento de um sistema, sendo
inclusive pensado e criado A TES do
início do desenvolvimento. Um bom
modelo de dados bem pensado e bem
estruturado não impacta somente em um
bom código, mas também na performace
da aplicação com um todo e na redução
de horas de desenvolvimento equivocado.
©  


ara criá-lo são utilizadas ferramentas de

modelagem de dados, as quais geram de
forma gráfica as tabelas, índices,
relacionamentos e tudo aquilo que tem a
ver com a base de dados em si, podendo
ser criados por meio de engenharia
reversa ou ainda baseando-se nas
necessidades do aplicativo que está
sendo desenvolvido.
©  

 As ferramentas mais conhecidas para

modelagem de dados dentro do mundo
livre são o DBDesigner
(http://www.fabforce.net), MySQL
Workbench (http://www.mysql.com) e
também o
Designer
(http://pgdesigner.sourceforge.net), as
quais possuem funcionalidades diferentes
e dispõem de versões tanto para Linux
quanto para Windows.
 .
?
  
 omo o próprio nome sugere, o dicionário
de dados nada mais é que um arquivo ou
documento que define a organização
básica dos dados do banco. ele são
informadas as tabelas, os campos, suas
definições, tipos e descrições (para que
serve este campo?). Um exemplo simples
de um dicionário de dados pode ser visto
a seguir:

?
  

 om um arquivo destes, mesmo simplório, em conjunto

com o modelo de dados, a possibilidade de erro na hora
do desenvolvimento fica extremanente reduzida, quando
falamos de acesso à dados na base, além de
economizar neurônios que muitas vezes estão sendo
usados para armazenar a informação que o campo
varodSysFil01 é o código de uma filial.

 

 Tão antigos quanto a computação, os

fluxogramas apresentam graficamente a
sequência lógica das informações de um
processo ou sistema, utilizando para isso vários
elementos de geometrias diferentes que indicam
cada uma das partes do processo. Sua
importância, mesmo deixada de lado, é grande
pois a partir dele (e conjuntamente com o
modelo e dicionário de dados), inicia-se o
projeto de um sistema eficiente e bem
desenvolvido.
 
 Da mesma forma que o modelo de dados,
fluxogramas são muitas vezes (mas não
deveriam) utilizados como pôsters de escritório.
Eles são mais que isso: visualmente conseguem
passar a lógica de todo um sistema desde os
níveis mais altos de processamento até
pequenas partes, permitindo assim uma visão
geral do que realmente precisa ser feito dentro
do sistema.
 Um exemplo de um fluxograma pode ser visto a
seguir:

 


ara criar fluxogramas, as mais conhecidas

ferramentas são:
 DIA (http://www.gnome.org/projects/dia) e o
OpenModeling (http://www.openmodeling.info),
ambas disponíveis em várias plataformas e
livres.
 http://s2i.das.ufsc.br/docs/s2idoc/index.html
 Exercício ± onstruir um fluxograma apresentando as etapas de
desenvolvimento de Software desde a análise de requisitos até a
documentação e implantação, especificando com mais detalhes a
Documentação.
?
 


ara muitos, a parte mais chata.
ara outros, a
mais importante. A documentação de código é
feita basicamente de duas formas: comentários
dentro do próprio código e geração de
documentação online (ou física).
 o primeiro caso normalmente o desenvolvedor
acredita que sua memória nunca irá falhar e que
somente ele irá colocar a mão no sistema,
deixando de documentá-lo e gerando problemas
gigantescos para si e para outros profissionais.
Um conjunto de comentários bem feito é tão
importante quanto uma lógica bem estudada.
?
 

 Funções, constantes, inclusão de arquivos,
campos de tabelas e outros elementos sempre
proliferam de forma exponencial dentro do
sistema, o que leva na maioria das vezes o
desenvolvedor a simplesmente criar novos
"remendos" com constantes "adicionais" ou
variáveis novas, pois não se recorda onde está
aquela função que formata determinado campo
(quem não passou por isso?).
 Um pequeno exemplo de um código bem
comentado pode ser visto a seguir:
?
 

 database->setQuery( query );
rows = database->loadObjectList();
 // establish the hierarchy of the menu
children = array();
// first pass - collect children
if (rows) foreach (rows as v ) {
pt = v->parent;
list = @children[pt] ? children[pt] : array();
array_push( list, v );
children[pt] = list;
}
// second pass - get an indent list of the items
list = mosTreeRecurse( 0, '', array(), children, max( 0, levellimit-1
) );
// eventually only pick out the searched items.
if (search) {
?
 


 Observe que não são necessárias

dezenas de linhas de comentários para
compreender o que determinada área do
sistema executa. Mas se estas simples
linhas forem deixandas de lado, além de
gerar um gasto desnecessário de horas à
procura de erros, aumenta-se o nível de
estresse de todos que irão mexer no
código e principalmente de quem paga por
ele.
?
 


ara a criação de documentação de código
online são utilizadas ferramentas que, baseadas
nos comentários existentes dentro do código,
permitem a geração de documentos que
efetivamente explanam o sistema de forma
macro, relacionando arquivos que são incluídos
em outros, funções, seus parâmetros e retornos,
constantes e uma infinidade de informações que
auxiliam qualquer desenvolvedor a
compreender o que é aquele "monstro" nascido
de suas mãos.
c



 Qualidade é um dos principais objetivos da

Engenharia de Software.
 Muitos métodos, técnicas e ferramentas são
desenvolvidas para apoiar a produção com
qualidade.
 Tem-se dado grande importância ao processo
como forma de se garantir um software de
melhor qualidade.´
c



Termo que pode ser definido de várias formas,

causando mal-entendidos:
1. Qualidade não tem um único sentido;
2.
ara cada conceito existem vários níveis de
abstração;
3. Visão popular pode ser diferente do seu uso
profissional.
c

 


 termo indefinível.
 pode ser sentida, discutida, julgada, mas
não pode ser medida;
 luxo, classe e elegância.
rodutos caros e
complexos têm melhor nível de qualidade.
onfiabilidade e o número de reparos
efetuados não são considerados.
c

 


 Qualidade é estar em conformidade com os

requisitos do cliente.
 Qualidade é antecipar e satisfazer os
requisitos dos clientes.
 Qualidade é escrever tudo o que se deve
fazer e fazer tudo o que foi escrito.
c



ë   ^ 



    


U
U
  
 


—

  
   

 
   

  
  

ÑU


  


  
       
 
  

 

 
 

     
 
  
c


   

c

  

Qualidade : ë   ! 


 
  "     
      ! 

 !

 #
Ex: Qualidade de um prato de  
comida está relacionado com  
 
a satisfação das necessidades:     
  
 "$ 
  
c

!
c



ë   ^


 
   

A certificação de qualidade oficial é emitida com base
em um padrão.
Ex. ertificados
i O selo do SIF
i O selo da ABI
i A classificação em estrelas dos hotéis
i Os certificados de qualidade da série ISO 9000
(padrão de qualidade) .
c

"
#


#



i ISO - International Organization for Standardization

i IEEE - Instituto de Engenharia Elétrica e Eletrônica
i AB T - Associação Brasileira de ormas Técnicas


  %& 
   
     
' $
 

  



()*+—,  $$  - 
   
. 
 
  
 
á  ! c



i 1900 - Inspeção pós-produção - avalia o produto final.

i 1940 - ontrole estatístico da produção.
i 1950 - Avaliação do procedimento de produção.
i 1960 - Educação das pessoas.
i 1970 - Otimização dos processos.
i 1980 -
rojeto robusto - avaliação do processo.
i 1990 - Engenharia Simultânea - avalia a própria
concepção do produto.
c








© : riar programas é uma arte que não pode

seguir regras, normas ou padrões.

U


 
 
$%


 
&%! '(
  
%



%

& ) %








& 
%
*á+




'

 
,&

 


  %
+'


-. &.



%
c




erspectiva Histórica da Engenharia de Software:

i anos 60 - Era Funcional
i anos 70 - Era do Método
i anos 80 - Era do usto
i anos 90 e depois - Era da Qualidade

Qualidade não é um fator de vantagem no mercado, mas é

uma necessidade para a garantia da competitividade.
c


/



/
 






.

 


 
  : padrão sistemático e
planejado de ações que são exigidas para garantir
a qualidade de software. Essas ações englobam:

i Aplicações de métodos técnicos

i Realizações de revisões técnicas formais
i Atividade de teste de software
i Aplicação de padrões e procedimentos formais
i
rocesso de controle de mudanças
i Mecanismos de medição
c


/



/ & 





   


i
lanejamento de qualidade
i Melhoria no processo e controle de qualidade
i erenciamento de qualidade no processo
i Análise de dados sobre a satisfação do cliente
 c




Ñ    
 
      


   

 

  
 

 
 
   

  
!     "
-

0 

.

 
 

 Visão que aborda a qualidade do produto

± 
 



 






 
 !"#$%&!'( #)*

 Visão que aborda a qualidade do processo

± ?      +   

 
  , , 
 
,  
 
  
-.
©  
     



 

 




x



1


$&©ë

ISO 9126 aracterísticas da qualidade de

produtos de software

BR 13596 Versão brasileira da ISO 9126

ISO 14598 uias para avaliação de produtos de

software, baseados na ISO 9126

ISO 12119 aracterísticas de qualidade de pacotes de

software (software de prateleiras)

ISO 12207 orma para a qualidade do processo de

desenvolvimento de software.

BR ISO 9001 Modelo para garantia de qualidade em

projeto, desenvolvimento, intalação e
assistência técnica (processo)
 




x



1



¦


U
  l
  I  r    li ç
   li   

r
c  s s
    s   
l i   t
 
s
ft  r . N
 
r  I , s
it
   c  it 
  rc  
.
P IU  P r
 t
  I /I U  r    li ç
 
I
r
c  s s
    s   
l i   t
  s
ft  r .
i    
  
r 
fic i l I ,  s


r
c  s s
 s t          t
.


I
c

 


   -
 ./ 0
arece difícil ...
 Muito se tem pensado sobre isso:
± ISO/IE 9126 - publicada em 1991.
± BR 13596 - publicada em agosto de 1996

Listam um conjunto de características que devem ser

verificadas em um software para que ele seja considerado
um software de qualidade
c

 
/

/ 
23456
U 
 12


 12
2 3   
   
2

12

 ci
li  ç
Pr

-s  fzr
 
(stisfz s 
r

ri

cssis ) c r ci z
 
r

s  ir
c
rrt
Itr

rili Itr c

s sists
s
cific
s
 rç  css
it css

 t
riz


s
U
f
ri st  c
r
c
 s 
rs,
lis, tc.
U
fiili t ri U
   fr
ci 
rst
(É i   fl s
fl s) T
lr ci  fl s c
rr
fl s, c

r
c
rili É c
z  rc
rr 
s 
cs
 fl s
sili Itliiili É f cil tr
c
cit
 
(É f cil  sr) 
licç


rsiili É f cil 
rr  sr

rci
li É f cil

rr  c
tr
lr
c

 
/

/ 
23456
U 
12


12
2 3  
   
2

12

fici
ci T

l
t

 rs

st,
(
i
  t
) l
ci.  c ç

c rs
s  t
rc rs
s rt
 t
t


 tiili lisili É f cil c
trr  fl ,
(É f cil   

c
rr

ificr)
ificili  f cil 
ificr  
tr
stili  r risc
 
s fz
ltrçs
Tstili É fcil tstr  
s fz
ltrçs
P
rtili 
tili É fcil 
tr 
tr
s
(É fcil  sr  its

tr
it) U
ci
r sr É fcill istlr 
tr
s
istl
its
U
f
ri st  c
r
c

rs 


rtili
U
ci
r É fcil sr
r s stit ir
tr

s stit ir sist
c

 
/

/ 
23456

omo aplicar a norma ISO 9126/ BR 13560?


ara avaliar um software segundo a norma deve-se tentar
atribuir valores (notas ou conceitos) a cada uma das
subcaracterísticas.
Fato: difícil aplicar a norma sem se estar familiarizado com o
processo de avaliação de software.
> ,  - descrevem,
detalhadamente todos os passos para se avaliar um
software.
c

 


{
  - =
4 

   

    0 -*


ara melhorar a qualidade no desenvolvimento precisa-se

de   
 para a descrição precisa e
formal das atividades do ciclo de vida do software.
 ©  {
 é representado por um conjunto
seqüencial de atividades, objetivos, transformações e
eventos que encapsulam estratégias para o cumprimento da
evolução do software
>7 
 


 A gerência de processo objetiva a geração de produtos de

acordo com o planejado e, ao mesmo tempo, melhorar a
capacidade de produzir software com mais qualidade.
 Melhor capacidade de lidar com o software:
{ # ompreender o estado atual do processo;
{ $Desenvolver uma visão do processo desejado;
{ % Estabelecer ações para a melhoria do processo;
{ & erar um plano para acompanhar estas ações;
{ ' ompreender os recursos para execução do plano;
{ ( Recomeçar a partir do { #

ara a evolução do processo de software é necessário ter
uma maneira para medí-lo.
©


*

 


 Modelo ^ 
)*

)*  (MM)
 +,-.///0%

rojeto ,{+

 Modelo
S
({  , 
!{ )

rojeto ,12+, etc
x"5//3
x"5

 uia para a aplicação da ISO 9001 para o

desenvolvimento, fornecimento e
manutenção de software, criado em 1993.

 Especifica requisitos mínimos para

assegurar a qualidade de produtos e
serviços, não definindo modelos ou
impondo sistemas de qualidade.
x"5//3 * 
! 

x"5

 Agrupa as atividades do ciclo de vida em 9 categorias:

i  
1
 

i  

     
 
i 4   , ,
i 4 
i  4 
i   ,
i 

i

 
i 
x"5//3 * 
 
x"5

 Estão organizadas em 9 itens:

i   

i
 

i   
i 
i 

 
,/
i  


i  
i    -
1
i 
x!á
x!á// x 

 Motivação
± Mortalidade dos trabalhos de padronização
 S
IE (Software
rocess Improvement and
apability dEtermination)
 Organização
± 4 entros Técnicos
± onselho Administrativo
± Organizações privadas e estatais
x!á
x!á// ". &8

  um conjunto de documentos
 onsiste de um !  de avaliação
± Facilita o auto-julgamento
± Desperta consciência do contexto
±
roduz um perfil do processo
± Direciona a adequação das atividades
± Apropriado para organizações de diversos
tamanhos
x!á
x!á// *


 Aplicado para organizações envolvidas com

qualquer atividade relacionada ás
atividades de computação
 A Avaliação examina o processo e
determina a efetividade deste
 Resultados podem usados para
± Auto-Avaliação
± Melhoria do processo

x!á
 O S
IE é composto por 9 partes:

parte 1: onceitos e uia Introdutório

parte 2: Modelo de erenciamento de
rocesso
parte 3: Avaliação do
rocesso
parte 4: uia para ondução de uma Avaliação
parte 5: onstrução, Seleção e Uso das Ferramentas de
Avaliação
parte 6: Qualificação e Treinamento dos Avaliadores
parte 7: uia para o
rocesso de Melhoria
parte 8: uia para Orientação da Determinação da
apacidade do
rocesso
parte 9: Dicionários
c
!


 
ë
 
   
ë   #   $  ë&# 
  %&  !
   

    " '& 

   
! " 
 
$ 


 #("
)   *  
  * 
'& $  
   
 ! &#! 
 
       + %& " $ 

  
 ! &#!
 # "    
'& 
$"

  $  $   
 $  
ë#& ,!   ,!    ! #"
 ! "
"
c
!


 
ë
 
  

*  -  #  #  #
  
  . /0
  +
 #  $
 
&    + %& " $
!
 .   +
&    "
 !!. #
 & 
!
"
1#2# -  -  ë
3&#

" 
" 
'& 
$
"
 ! (4 # " 5! 3" 1
 ë&#  
 %&# 
 
,! 3

 "
 ë
     

  #  %

 9 . ë.
  .  . . .
  . 8 . 
" 9::7 .
 # 6 
   #
#
 # 
#.

7
" 

 
"
%
 
  #

 


 
  


 ##$


#
   #
 

#


" 
% " 
"

:  
 
  # 

#
  
 
; 
#


    
;



'

$ " 


#"  #    
ë 6  
#
 
 "



; #

 

# 


% "


$ " 



"
# 



# 




"


"
!  

 Dos métodos de avaliação de processo apresentados,

alguns estão estabelecidos no mercado (MM), e outros
apresentam projetos ambiciosos a nível mundial
(S
IE).

 Dentre estes, existem modelos que além de avaliar o

processo de desenvolvimento propõem algum
mecanismo para melhoria do processo.
!  

 ão existe um modelo ideal de avaliação de

qualidade que seja aplicável indistintamente às
organizações, abrangendo os diversos objetivos
que elas tem em relação a qualidade.
 A qualidade de software não é garantida somente
pela qualidade de processo, mas também pela
garantia de qualidade do produto final.
 A maior preocupação deve ser sempre a
satisfação do usuário final.
Alguns endereços na Web:
 http://www.sei.cmu.edu/cmm/cmm.html
 http://www.ISO_online.com

 Outras normativas qualidade

 MMI - M
SBR