Author: tziade
Date: Fri Mar 24 23:33:25 2006
New Revision: 2719
Modified:
cookbook/trunk/recipe50.en.tex
Log:
save point, started translation
Modified: cookbook/trunk/recipe50.en.tex
==============================================================================
--- cookbook/trunk/recipe50.en.tex (original)
+++ cookbook/trunk/recipe50.en.tex Fri Mar 24 23:33:25 2006
@@ -3,6 +3,7 @@
\include{macros}
\status{draft}
\author{Tarek Ziad�}
+\translator{Tarek Ziad�}
\begin{document}
@@ -10,11 +11,165 @@
functional testing}
\begin{problem}
-Not translated in english yet.
+Coding, testing, documenting, coding, testing, coding, testing...
+
+The good pace of the different activities of a developer daily job is hard
+to find. In ends of projects, the rush and the stress often reduce the
+testing and the documenting parts, so the work can be finished on time. But
+this shortcut often leads to backdrafts later: end of projects are often
+periods where the code is highly refactored.
+
+This problem can be partly reduced with good practices explained in this
+recipe. They apply to Zope of course, but the principles are the same
+for other Python project.
\end{problem}
\begin{solution}
-Not translated in english yet.
-\end{solution}
+\section*{Understanding the developer duties}
+
+A developer has three duties:
+\begin{itemize}
+\item Coding;
+\item documenting;
+\item testing;
+\end{itemize}
+
+The first phase is of course TDD coding. The a cycle of functional tests
+is made. The the code might be changed, to add new features, changes, etc.
+Theses cycles are well documented and explained in methodologies like
+RUP (IBM Rational Unified Process). This is out of topic though, but
+interested readers can get complementary informations on Rational website:
+
+\url{http://www.rational.com}
+
+\section*{Creating the code}
+
+To create a new feature, the developer gets a feature request, made of
+functional specifications and sometimes technical specifications.
+
+Using this document, she creates the code following these steps:
+\begin{itemize}
+\item Transcripting in a reST document (doctest) the specifications;
+\item inserting code examples, that fullfills the features asked;
+\item coding the underlying code, so the examples in the document
+works for real.
+\end{itemize}
+
+\subsection*{Transcripting the need into a doctest file}
+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+Transcrire en doctest les besoins exprim�s se fait en synth�tisant au maximum
le
+cahier des charges, et en d�crivant la structure du paquet qui va �tre
+d�velopp�.
+
+Prenons l'exemple d'un module en charge de r�cup�rer des flux RSS pour les
+stocker dans des objets Python persistants, puis les rendre affichables dans
+l'application. Le d�veloppeur d�cide d'organiser son paquet en trois modules:
+\begin{itemize}
+\item \code{rssfetcher.py}: module en charge de la r�cup�ration des flux RSS;
+\item \code{rssobject.py}: module en charge de la cr�ation et du stockage
+des donn�es;
+\item \code{rssview.py}: module en charge de l'affichage des donn�es.
+\end{itemize}
+
+\noindent Il commence par �crire quatre fichiers doctests, qui expriment cette
+structure:
+\begin{itemize}
+\item \code{README.txt}
+\item \code{rssfetcher.txt}
+\item \code{rssobject.txt}
+\item \code{rssview.txt}
+\end{itemize}
+
+Le fichier \code{README.txt} d�crit en quelques phrases l'objectif du paquet,
+et pr�sente sa structure.
+
+\codetitle{Fichier README.txt}
+\begin{Verbatim}
+rssreader
+=========
+
+Ce paquet permet de pr�senter des flux rss. Il est organis� en trois
+composants:
+
+- rssfetcher: sait lire un flux RSS 1.0
+- rssobject: stocke le flux et fourni des m�thodes d'acc�s
+- rssview: sait afficher un flux dans le navigateur
+\end{Verbatim}
+
+\noindent Chaque module est pr�sent� � son tour dans un doctest.
+\codetitle{Fichier rssfetcher.txt}
+\begin{verbatim}
+rssfetcher
+==========
+
+Le module rssreader transforme un fichier XML au format RSS 1.0
+vers une structure Python exploitable. Il est invoqu� avec l'URL
+d'un flux et renvoi une liste contenant les entr�es du flux.
+\end{verbatim}
+
+A ce stade, le d�veloppeur n'a pas encore �crit de code, mais
+dispose d'une sp�cification technique et architecturelle exploitable.
+
+\subsection*{Ins�rer des exemples de codes}
+
+Sur la base de ces fichiers textes, le d�veloppeur peut commencer
+� pr�parer le d�veloppement des modules, en explicitant la face
+visible de ces derniers, c'est � dire les API qui seront utilis�es
+dans d'autres modules.
+
+\codetitle{Modification du fichier rssfetcher.txt}
+\begin{verbatim}
+rssfetcher
+==========
+
+Le module rssfetcher transforme un fichier XML au format RSS 1.0
+vers une structure Python exploitable. Il est invoqu� avec l'URL
+d'un flux et renvoi une liste contenant les entr�es du flux.
+
+Il fourni une fonction `fetchFeed(source)` qui renvoie une structure Python
+en fonction d'une URL ou d'un fichier ::
+
+ >>> from rssfetcher import fetchFeed
+ >>> fetchFeed('tests/rss.xml')
+ [{'Subject': 'entry one', 'content': "le contenu est ici"}]
+
+\end{verbatim}
+\begin{codenotes}
+\item Le paquet doit pr�voir dans un sous r�pertoire un fichier
+�chantillon \code{rss.xml}, contenant un flux utilis� pour les tests.
+\end{codenotes}
+
+\noindent Ce principe est appliqu� pour l'ensemble des modules du paquet,
+susceptibles de fournir des fonctionnalit�s.
+
+\subsection*{D�velopper les fonctionnalit�s}
+
+Le doctest pr�c�dent ne peut bien s�r fonctionner que si l'impl�mentation
+est r�alis�e. Le d�veloppeur con�oit donc le module \code{rssfetcher.py}
+jusqu'� ce que le test du doctest passe. Ce d�veloppement n�cessitera
+certainement la cr�ation d'autres tests unitaires, qui seront
+con�us classiquement dans des classes dans le sous-r�pertoire de \code{tests}.
+
+Lorsque tous les modules sont con�us, \code{README.txt} contient un exemple
+complet d'utilisation, qui simule g�n�ralement quelques directives ZCML
+et quelques �changes avec le publisher.
+
+\section*{Maintenir et faire �voluer le code}
+
+L'�volution du paquet, que ce soit dans le cadre d'une correction, ou
+d'une modification, doit se faire de la m�me mani�re: les fichiers textes
+sont revus en premiers, puis le code est modifi� en cons�quence.
+
+Les corrections de bogues sont trait�s d'une mani�re particuli�re:
+un test unitaire qui reproduit le probl�me est ajout� dans les classes de
+tests, et le code invoqu� corrig�. Ajouter ces tests dans les doctests
+d�nature leur objectif secondaire: servir de documentation.
+
+Cependant, si il est explicitement demand� que les bugfix soient document�s,
+et facilement lisibles, un doctest \code{bugfix.txt} peut �tre ajout�.
+Ce n'est pas le cas pour Zope 3 par exemple, car le couple tracker+svn fourni
+une bonne tracabilit� des bugfix.
+\end{solution}
\end{document}
--
http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins
