[Desenvolupament] Llibreria libcatz

[Jordi Mas]

Hola Jordi,

> Això és deformació professional. Intentar que el codi s'ajusti al màxim 
> a les llibreries ANSI C, ANSI C++, STL etc.. per si algun dia volem que 
> pugui compilar amb qualsevol compilador.
> 
> Així, en el cas del fitxer de log proposo utilitzar _wfopen enlloc de 
> CreateFile, fclose enlloc de CloseHandle, etc...
> 
> En el cas de les dates enlloc d'utilitzar el GetLocalTime proposo 
> utilitzar _ftime64 i _localtime64.
> 
> Tots aquests canvis els he implementat i la generació del fitxer queda 
> exactament com en el cas del Catalanitzador actual.

Qualsevol compilador al que en el futur migrem haurà de tenir suport pel 
Windows API ja que el Catalanitzador és una aplicació Windows que usa el 
seu API extensivament[1]. Per exemple el gcc per a Windows, Borland o 
qualsevol altre ofereixen suport a l'API de Windows.

Llavors, aquests canvis no ens donen cap flexibilitat real.

Una cosa diferent seria que estiguessis fent el porting per poder 
compilar amb gcc i que calgues fer aquests canvis per poder-ho fer, però 
no és el cas i tampoc són necessaris.

> using namespace std;
> 
> A mi particularment no m'agrada donat que es perden les avantatges dels 
> namespaces. Prefereixo escriure més, però tenir més control del que 
> toco. Si cal escriure "std::cout << std::endl" el codi queda una mica 
> més comprensible i evitem errors.

És una qüestió d'estil.

Per exemple, l'estil del Catalanitzador és com funciona Java o C# per 
exemple: declares els namespaces que vols usar i després pots fer 
referencies a ells de forma més curta i sintètica.

> En treballar amb el fitxer LogFile, i per evitar tocar l'interface que 
> utilitzes he fet el següent:
> 
> files::LogFile -> files::filebase
> files::ffile : accés al fitxer de log
> 
> En la classe filebase tinc un punter a un fitxer ffile que és el que 
> realment accedeix al fitxer. ffile acaba estant com a private de 
> filebase, de manera que queda protegit i al mateix temps el FILE* dins 
> de ffile també és private protegint el seu valor i l'accés.
> La classe filebase únicament té sentit per a protegir la interface que 
> estàs utilitzant. He tret algunes rutines protegides de Logfile per a 
> posar-les dins de filebase.

En la meva opinió, el principal problema de LogFile és més greu. Es veu 
de seguida:

g_log.Log(L"MSOfficeLPIAction::_setDefaultLanguage, set FollowSystemUI 
%u", (wchar_t *) bSetFollowKey);

El fet que no funcioni com un pipe i que calgui fer tots aquests 
castings. Canviar això realment té risc, ho vaig provar.

> En el cas de 'HANDLE m_hLog' es pot escriure en ell des de diversos 
> punts dins de la classe mateixa i en cap d'ells es comprova si el valor 
> de la variable té un valor bo. De fet et disparará una excepció 
> l'aplicació si no crides CreateLog un cop has creat l'objecte.
> Ja t'he comentat que estic molt pervertit pel meu món de programació, i 
> potser no fa falta controlar tant el codi, encara que crec que pot ajudar.

> Caldria que les classes i el codi mantinguéssin un mateix Coding Standard.
> 
> - Una de les coses que m'agrada és el '_' que afegeixes davant de les 
> rutines protegides i que utilitzaré a partir d'ara en els meus 
> desenvolupaments futurs.

Això ve de la necessitat d'haver de tenir mètodes amb signatura 
'protected' per tal de poder fer proves unitàries. Llavors, per això 
faig servir aquesta nomenclatura.

> - He vist també que en alguns casos utilitzes 'm_' davant de variables 
> de classe i en d'altres no. A mi m'agrada afegir '_' al final de la 
> variable per a protegides i '__' (2 _) per a les privades.

És qüestió de conveccions, al final s'ha d'escollir una o un altre i cap 
és millor que altre.

> - Respecte als if (...) una cosa que podries fer i que el MISRA C 
> recomana és posar el valor de la constant abans per a que el compilador 
> t'avisi si t'equivoques: (0 != variable) enlloc de (variable != 0). Això 
> evitaria errors difícils de trobar com if(variable = 0) // ==

He vist aquesta practica, en general hi ha molts pocs programes lliures 
que la segueixin.

> - A l'entrada de rutines caldria afegir comprovacions de validesa i de 
> rang utilitzant 'asserts' per a que al "debugar" cantin els errors.

He afegit alguns allà on aporten valor immediat, com la màquina d'estats 
de les accions[1]. Els asserts són una bona cosa.

> - Utilitzar el modificador 'const' per a variables d'entrada i no sortida.

Els const certament no s'usa tot arreu on es podria usar. Ho trobo una 
molt bona cosa.

> - A la classe LogFile he afegit una rutina writeLog(const wchar_t* 
> format, ...)  similar al printf per a evitar la sobrecàrrega de 
> Log(wchar_t*), Log(wchar_t*,wchar_t*), etc...
> La referència està força bé.
> 
> Espero que les propostes t'agradin, no sóc ningú per a fer res sense el 
> teu consentiment. Això em pot donar molta feina i crec que pot ajudar al 
> manteniment i clarificació de tot el codi.

El problema que hi ha amb els canvis és que molts d'aquests canvis tenen 
molt poc valor funcional (impacte per l'usuari) o no redueixen 
significament el cost de manteniment, i poden tenir un impacte en 
introduir noves errades. Veure el pla de proves per fer-se una idea[2] 
del que cal provar cada vegada que fem canvis significatius.

Si em preguntessis que penso que cal prioritzar seria:

1) Ampliar la cobertura de proves unitàries que ens ajudin a reduir les 
proves que hem de fer i la feina amb el procés de proves[2]. Això ens 
permetrà:

- Alliberar versions més sovint amb menys esforç
- Fer refactorings en el futur amb menys risc

2) Ampliar la funcionalitat. Hi ha una llista d'errors i coses a fer 
molt important [3]. Algunes petites però interessants i importants. La 
podem prioritzar.

3) Fer 'refactorings' de baix risc que facilitin el manteniment.

Dels canvis que proposes jo els hi veig més valor a: introduir const, 
asserts i els canvis que introdueixen consistència amb el que hi ha fet 
(per exemple, noms de variables).

Atentament,

Jordi,

[1] 
https://github.com/Softcatala/CatalanitzadorPerAWindows/blob/master/CatalanitzadorPerAWindows/Actions/Action.cpp#L94
[2] 
http://www.softcatala.org/wiki/Projectes/Catalanitzador_Per_Al_Windows/Pla_de_proves_versi%C3%B3_1.2
[3] 
http://www.softcatala.org/wiki/Projectes/Catalanitzador_per_al_Windows/Coses_a_fer
-- 
Jordi Mas i Hernàndez -Bloc: http://gent.softcatala.org/jmas/bloc/
Planet Softcatalà -> http://planeta.softcatala.org