Consejos para documentar

[ring]

qué aconsejan para hacer una documentación interna y externa COMPLETA  de un programilla en PASCAL?

[JorgeAVM]

¿El programa lo hizo usted?

[ring]

pues lo hice pero no sé qué àja comentar

necesito agregarle documentación, pero como es tan sencillo y no sé qué pasos se acostumbran, he leído que se ocupan para documentacion interna o se debe poner precondiciones, postcondiciones, explicacion de los parametros y valores de retorno mas un comentario de q hace el procedimiento, pero como es tan sencillo, no sé qué inventar, es elemental, se lo voy a postear.

Codificación
A continuación se transcribe:

{Comentario: este programa responde al planteamiento de la Tarea 4}

Program Libros (input, output);
(* Recibe 100 libros como máximo de libros leídos y devuelve la información de cuántos son de los noventas y cuantos del 2000 en adelante *)

Uses crt;

Const
  CANTIDAD_LIBROS = 100;

Type

  TLibro = record
    titulo : string;
    autor : string;
    precioCompra: real;
    añoEdicion : integer;
  end;

var
  arregloLibros : array [1..CANTIDAD_LIBROS] of TLibro;
  masLibros : integer;
  indice : integer;

procedure reportarAño90(cantidadLibrosLeidos : integer);
var
  cantidadLibros : integer;
  i : integer;
begin
  cantidadLibros := 0;
  for i := 1 to cantidadLibrosLeidos do
     begin
      if ((arregloLibros.añoEdicion >= 1990) and (arregloLibros.añoEdicion < 2000)) then
        begin
          inc(cantidadLibros);
        end;
    end;
  write('Cantidad de libros de los 90s: ');
  writeln(cantidadLibros);
end;

procedure  reportarDespues2000(cantidadLibrosLeidos : integer);
var
  cantidadLibros : integer;
  i : integer;
begin
  cantidadLibros := 0;
  for i := 1 to cantidadLibrosLeidos do
    begin
      if (arregloLibros.añoEdicion >= 2000) then
        begin
          inc(cantidadLibros);
        end;
    end;
  write('Cantidad de libros del 2000 en adelante: ');
  writeln(cantidadLibros);
end;
procedure reportarResultados(cantidadLibrosLeidos : integer);
begin
  reportarAño90(cantidadLibrosLeidos);
  reportarDespues2000(cantidadLibrosLeidos);
end;
begin
  clrscr;
  masLibros := 1;
  indice := 0;
  while ((masLibros = 1) and (indice <= 100)) do
    begin
      inc(indice);
      write('INFORMACION DEL LIBRO: ');
      writeln(indice);
      write('titulo: ');
      readln(arregloLibros[indice].titulo);
      write('autor: ');
      readln(arregloLibros[indice].autor);
      write('precio: ');
      readln(arregloLibros[indice].precioCompra);
      write('a¤o edicion: ');
      readln(arregloLibros[indice].añoEdicion);
      write('mas libros? (0 : no, 1 : si): ');
      readln(masLibros);
    end;
  reportarResultados(indice);
  writeln('Presione una tecla para continuar ...');
  readkey;

end.

[JorgeAVM]

Bien, la documentación interna, es agregar comentarios en el código del programa que ayuden a comprender qué hace el código en cada parte importante.
Por ejemplo:

Centre Me ' Centra el form
Dev_CAFF.VerEBAIS  'Cargar información del EBAIS
If Dev_CAFF.rsVerEBAIS.RecordCount > 1 Then MsgBox "Error de Base de Datos, tabla: Caff_Ebais. Hay más de un Ebais. Consulte con el proveedor del Sistema", vbCritical
Txt_IdeEbais.Text = Dev_CAFF.rsVerEBAIS.Fields(0).Value
Txt_DscEbais.Text = Dev_CAFF.rsVerEBAIS.Fields(3).Value
Txt_IdeArea.Text = Dev_CAFF.rsVerEBAIS.Fields(1).Value
Txt_IdeRegion.Text = Dev_CAFF.rsVerEBAIS.Fields(2).Value
Dev_CAFF.rsVerEBAIS.Close
'------------------------

En este ejemplo, el texto en rojo representa la documentación interna.

La documentación externa, es mucho más elaborada que eso, dependiendo del caso puede requerir un manual de usuario, en el cual explica paso a paso cómo usar el programa. También podría requerir un manual técnico en el cual pueden ir cosas tal como la instalación del programa y sus requisitos de equipo.

[gin]

Es importante no llenar de comentarios reduntantes, solo aquellos procedimientos o instrucciones un poco extraños o complicados, que luego de 3 años intendo saber para que lo hicimos.  

Por cierto que tiene que ver este mensaje con el subforo  :?

[JorgeAVM]

nada.
¿Porqué la pregunta?

[Link]

Porque esa pregunta este subforo es de Pascal, Delphi y el pregunta como documentar un codigo en Pascal. Yo no veo nada mal.

[gin]

Ahora si.

Pero que raro lo vi en Juegos y Emuladores de Consolas  :shock:

[Link]

A ya seguro fue un dedazo.

[JorgeAVM]

Bien! :wink: