Ese día llegó

[[AgustinOrtu]]

Hola nuevamente Al

Estuve explorando un poco el codigo, pero aun no he puesto en marcha ninguna prueba

Solamente tengo un par de comentarios para hacerte:

- Me alegra que uses identificadores calificados. A mi tambien me gusta hacerlo y creo que crear bibliotecas publicas es una buena forma de impulsar al resto a que haga lo mismo. Solamente hay una pequeña diferencia en como lo hago yo; yo prefiero seguir la convencion que esta adoptando poco a poco Firemonkey, en la cual, el prefijo para los elementos del tipo enumerado ya no se usa

Por ejemplo, de GHF.Sys, linea 528

Código Delphi [-]
  TDirectionSide = (eSource, eDest);

Esto nos lleva a escribir codigo asi:

Código Delphi [-]
procedure Foo(const Direction: TDirectionSide);
begin
  if Direction = TDirectionSide.eSource then
  begin
    //  
  end;
end;

Yo creo que el prefijo que historicamente se uso en Delphi (pensando tambien en TAlignLayout --> alClient, alTop, etc) no es necesario si se usan identificadores calificados y "ensucia" el codigo fuente.

Otro detalle que creo que es importante, veo que en tus unidades siempre activas la directiva de compilacion SCOPEDENUMS

Ahora me entro la curiosidad, pero yo creo que lo mas seguro es compilar nuestros tipos enumerados con la directiva y luego volver a ponerla a OFF que es su valor por defecto. Es decir, asi es como yo declaro los tipos enumerados:

Código PHP:

{$SCOPEDENUMS ON}
  /// <summary> The diferent scopes that a Token is allowed to operate on </summary>
  TTokenScope = (
    /// <summary> The Token may Read data </summary>
    Read,
    /// <summary> The Token may Write data </summary>
    Write,
    /// <summary>
    ///   The Token may operate on a Offline basis, that is, the user grants permission once and then the bearer may
    ///  request a refresh without explicitly asking the user
    /// </summary>
    Offline_Access
  );
{$SCOPEDENUMS OFF} 


Esto me asegura que si o si se deba prefijar el tipo para poder utilizar alguno de los valores, que es el efecto deseado

- Otra recomendacion es el uso de regiones para hacer el codigo mas legible. Las regiones te permiten [plegar?] porciones del codigo y denotarla con un nombre, para hacer mas facil la navegacion dentro de la unidad. Es mas largo hacer scroll en una unidad larga como por ejemplo las GHF.Sys y GH.SysEx. Tambien creo que es una buena idea usar una region para la licencia, que ocupa su buena porcion de espacio

- El ultimo punto es el uso de la documentacion XML. Esta es una de las ultimas practicas que he adoptado, y ya me he acostumbrado. Consiste en documentar el codigo de forma tal que pueda ser util al momento de que el usuario use tu biblioteca, y no tenga que tener un manual de referencia para consultar. Esta documentacion XML se adjunta en la ventana que aparece cuando Delphi nos muestra cuales y que tipo de parametros recibe un metodo, el retorno de una funcion, etc

Si hoy escribo alguna clase, metodo, funcion, tipo, lo que sea, sin incluir la documentacion XML, me siento mal conmigo mismo (es similar a tu comentario cuando hablamos de esto). De hecho en muchas ocasiones me ha pasado que es dificil explicar que es lo que deberia hacer el metodo en cuestion, y es cuando detecto un error de diseño que debe ser refactorizado incluso antes de escribir codigo; tambien existe el caso de que no se me ocurre como escribir el codigo, pero al escribir la documentacion luego se hace mas facil la implementacion

El efecto logrado es el siguiente:

Código PHP:

unit Vcl.WinControl.Helper;

interface

uses
  Vcl.Controls;

type
{$REGION 'TWinControlHelper'}
  TWinControlHelper = class helper for TWinControl
  public
    /// <summary> Intenta darle foco al control; devuelve True si tuvo exito, False en caso contrario </summary>
    /// <remarks> Este metodo captura y controla excepciones </remarks>
    function TrySetFocus: Boolean;
  end;
{$ENDREGION} 


Las ultimas vesiones de Delphi, en sus bibliotecas mas nuevas, escriben esta documentacion en linea y me ha ayudado mucho, por ejemplo la unidad REST.Json

Código PHP:

  TJson = class(TObject)
  public
    /// <summary>
    /// Converts any TObject descendant into its Json representation.
    /// </summary>
    class function ObjectToJsonObject(AObject: TObject; AOptions: TJsonOptions = [joDateIsUTC, joDateFormatISO8601]): TJSOnObject;
    /// <summary>
    ///   Converts any TObject decendant into its Json string representation. The resulting string has proper Json
    ///   encoding applied.
    /// </summary>
    class function ObjectToJsonString(AObject: TObject; AOptions: TJsonOptions = [joDateIsUTC, joDateFormatISO8601]): string;

    /// <summary>
    ///   Encodes the string representation of a TJSONValue descendant so that line breaks, tabulators etc are escaped
    ///   using backslashes.
    /// </summary>
    /// <example>
    ///   {"name":"something\else"} will be encoded as {"name":"something\\else"}
    /// </example>
    class function JsonEncode(AJsonValue: TJsonValue): string; overload;
  end;