Coding support process for the Qualdev Group

Texto completo

(1)Universidad de Los Andes. Coding support process for the QualDev group. Undergraduate final project. Hernán Camilo Quevedo Barrero May 2008. Instructor: Nicolás López. Department of Computer Science.

(2) Table of contents Introduction……………………………………………………….………3 Justification……………………………………………………….….…....4 Objectives……………………………………………………………….....5 Related work……………………………………………………………....6 QualDev: current state…………………………………..……….….…..13 ESPRO…….....……………………………………………………….…..15 The process..……………………………...……………………………....17 Validation tool……..………………….………………………….……....28 Conclusions……………………………………………………………....35 References..……………………………………………………………....38. 2.

(3) Introduction The intention of this document is to introduce the reader with a coding support process, taking as case study QualDev group. The process, will be executed in the context of the current developing and engineering processes, specifically around its Specification and Definition of. Processes’ (ESPRO). The process intends to be a guide for developers to help them in the coding phase, following standards that will enable better understanding of that code when they are gone. Also, the process aims to help new programmers to be self-aware of the code they are understanding, changing and/or improving. First, I will mention a short justification of this work and then a list of objectives will be presented to give the reader a global vision and a path to be followed. Next, I will revise related works according to current SW literature to put this work in context and give the reader a notion of precedents. Subsequently, I will analyze QualDev current practices on coding documentation process to make room for the new process, using a temporary job in a software house as a comparative case study. After that, the process itself will be presented formatted to QualDev standards of process definition. Finally, I will evaluate the viability of a prototype validation tool that aims to become an option for the Eclipse perspective1.. 1. http://qualdev.uniandes.edu.co/wikiDev/doku.php?id=development:projects:eclipseplugin:eclipse/. 3.

(4) Justification Documentation processes at QualDev are almost non-existent; there is documentation, but solely focused on general views of the application as class diagrams, web-state diagrams, security module diagrams and deployment views, with some sequence diagrams. Although to-do documentation is out of the scope of this work, the lack of a clear guide for writing and documenting Java code in any of the projects at QualDev represents a risk since code produced could not fulfill expected standards, becoming error prone and making debugging a complex task. QualDev, on the other hand, has a high turn-over rate, which leaves the burden of understanding old code entirely to the experience of programmers with some external help from former members. Code from Changeset, as example, requires programmers to understand various interfaces and implementing classes over several packages describing distinct functionalities. This code can get quite confusing, and having a clear process to follow when coding, becomes critical. Comments and annotations added to files are necessary what a particular segment of code does and where it stands in the big picture. The process should help students do these things and then, debug, improve and delete code reducing the impact or probability of introducing new bugs. This approach is also a result of my personal experience in Changeset and as a junior developer on a code migration for a PHP-based web site. This process will be useful in that it will be used to point out poor documentation. practices. with. their. associated. problems. when. appropriating other people’s code, especially during maintenance and enhancement cycles.. 4.

(5) Objectives General objectives The global objective of this work is to define a process for the coding phase in QualDev. All projects at QualDev can benefit by integrating this new process. Specific objectives • Create a coding a documentation support process consistent with the Software Development Process (SDP) in QualDev. • Test the process with some interfaces and classes from Changeset, documenting them according to this new process. • Give feedback for the SDP and publish the new process at the group’s process wiki-site, to make it accessible for the whole community. • Provide support to coding, specifically in the form of guides and templates to follow. • Supply a checklist to verify the documentation done on a java file. • Research into the viability of implementing validation tools for this process, and outline their design. As a somehow of future and global objective, make this tools a new perspective in Eclipse.. 5.

(6) Related work Information and communication technologies (ICT) are currently critical tools for any business model or business strategy; they are at the company’s administrative core and manage all important data in the form of business logic. QualDev can be seen as a business model in the form of academic research of Software Development Processes. Software delivers the most important product of our time—information. Software transforms personal data (e.g., an individual’s financial transactions) so that the data can be more useful in a local context; it manages business information to enhance competitiveness; it provides a gateway to worldwide information networks (e.g., Internet) and provides the means for acquiring information in all of its forms [Pressman]; that is why it needs to be constantly upgraded to assure better maintenance and improvement. “Processes are at the centre of software development. They can be seen. as a flow of actions with inputs and expected results, i.e., when analyzing a problem and outputting a document as product, which itself serves as input for further analysis or designing”2. SDP is itself a process definition and it has been specified using several standards, such as SPEM, where processes are defined as collaboration between entities that perform activities on other type of entities [JS] defined in UML3. RUP4 is complaint with the SPEM specification and manages the SDP as an iterative and incremental process [JG]. Most models we can find in 2. Developing through a classic life cycle SW model or the waterfall model, where you have a domain analysis with phases (planning, analysis, design phase, etc.). 3 http://www.omg.org/cgi-bin/doc?formal/2008-04-01 4 http://www-306.ibm.com/software/awdtools/rup/. 6.

(7) literature converge in that software must be developed continuously, in an incremental way, so quality is effectively achieved within time boundaries. The issue here is that SDP tries to solve the problem of managing resources (human and technological), defining requirements of a given scenario for consumer needs, designing the best possible solution, organizing the development of it and maintaining that solution. Software deals with a particular and tailored problem, offering distinct services but models of SDP try to elucidate the problem-solver problem: conception of a general method for building software. In fact, all software development can be characterized as a problem solving loop in which four different stages are encountered: status quo, problem definition, technical development and solution integration [Pressman]. There are some of the industry-approved standards to begin comparison focused in finding one which be closely related to this work. CMMI informs your group whether they are completely capable of performing that discipline and assesses as a reference model to measure the level of maturity of your group’s followed processes5. Although is an industry standard these days, it does not address the particular issue of software process for coding and documenting phase, nor whether a project’s code in particular can influence the project. RUP concentrates on an iterative and incremental process, it is based on use-cases based but like CMMI, does not consider specifics of coding practices or the importance of a thorough documenting process while coding. 5. http://www.sei.cmu.edu/cmmi/presentations/sepg04.presentations/upgrade-strategies.pdf. 7.

(8) On the other hand, the Caos model proposed by L.B.S. Raccoon, primordially focuses on software development, extends the waterfall and spiral models and see the phases of the software cycle applying to all levels in a project.6. L. B. S. Raccoon [RAC95] suggests the above picture using fractals as the basis for a discussion of the true nature of the software process. As a matter of fact, Raccoon goes to the level of lines of code and their role in the entire project, taking into account that, ultimately, developers do all the job [ACM].. The fractal becomes evident and a pretty good idea of what a process means when developing a piece of software can be inferred: regardless 6. http://www.swcp.com/raccoon/chaosmodel.html. 8.

(9) of the process model that is chosen for a software project, all of the stages coexist simultaneously at some level of detail [Pressman]. I think we are getting closer to CSP intention: bring the deserved attention to the code phase, point out that ultimately, functional requirements might be achieved in a better way due to a developer’s particular coding style, formatting and choosing certain expressions in a LOC. “I use fractal phase definitions to show that the phases resemble each. other. I show that we can view the whole life cycle in terms of each phase and view each phase in terms of the whole life cycle. By transitivity, the phases are essentially identical. So, our assessment of where a project is shows our perspective about the project, rather than any essential truth about the project.” [RAC95] This approximation to a new documenting and coding support process will be framed into the Chaos model, as it appears to be the most related subject to my proposal.. JAVA API STANDARDS Sun Microsystems have defined the standard for the Java Platform API Specification when commenting and documenting java source files. As can be found online, there are suggested practices when coding that can facilitate in a number of ways the life cycle of an application, when extending functionalities, debugging, adapting, etc.. In order to have a nicely done javadoc, ready to visualize in HTML, asterisks, delimiters and tags are explained as tools for commenting adequately as well as forms for writing.. 9.

(10) For example, for methods, Sun recommends using 3rd person sentences instead of prescriptive ones (2nd person); begin method descriptions with verbs, referring to the actions taken by methods using “this” to mean that the object itself is receiving the action; the first sentence of a doc comment should be a summarizing one; describe beyond the API name, which is very important when documenting a source file. These rules are not at the core of CSP since they are taken for granted. Developers should be able to realize that describing a class, its attributes and methods is a pretty basic process when coding. Nonetheless, CSP takes into account all of this to make it a process, a very important one. Source files formatted this way rapidly become remarkable over others with random and lacking styles. Although there is no standard for indentation and the code is simply messy, a way or concrete practice to document LOCs is not explicitly given on this specification and is left to the programmer’s criteria. CSP precisely addresses this issue and validates it taking the practices described at Sun. Not only it is imperative to realize that a group’s process is a milestone, but also to realize that software is essentially lines of code, sequential instructions, no matter what organization or form might take (components, models, aspects) the details remain the most important issue: its body, its LOCs. I see the necessity of explaining a single line of code; I see this as some sort of global ultra-rapid programming course that could help even a novice programmer feel already capable of factorizing LOCs and debugging the code. Global in that it might go from simple POJO programming to EJB and enterprise logic programming.. 10.

(11) Again, the Java API gives then a great example on how to correctly use javadoc, a little on how to comment lines of code and a lot on how to get documentation ready and complete. Another good recipe can be found at http://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle,. although. is. pretty much what Sun says. We can see how this standard works at Sun by holding the Ctrl key and left-clicking on the name of a method from the Java API, like in image 3.. Image 3. The method back there is put(K key, V value) from the Dictionary abstract class, which, by the way, has its own method description and the implementing class here, Hashtable, has another description, similar to the super-class but with additional explanation. Three things to note. One, the indentation standard here is more by instinct than with the intention of being comprehensible; two, in spite of that, there are comments beginning blocks of code to remember effectively what is that code doing there. And three, at the start of the file, there are non-javadoc comments (green letters) mentioning what class is it, version, date and copyright, and it is not used for references as with the. @see tag whatsoever.. 11.

(12) A poor example I had the opportunity to participate in a small house of software writing code in PHP as a web master, correcting different kinds of problems with HTML display and scripting pages away from misuse by final users. The biggest problem that came across was looking up for that errors in scripting: it was incredibly hard and exhausting. All PHP files in KEX website look like this:. Image 5. This is a common practice among PHP developers, although they know is nowhere near good they tend to do this due to time limitations and bad planning. Aside from technical bugs I had to deal with (like the tag to begin a PHP sentence and Apache), reading this code means reading one line and then go to another included page to get the idea behind some squalid function name like “GetOne”, and for a lot of variables set on other pages like session ones.. 12.

(13) There are unfeasible issues like code embedded HTML and tags all over the place, inherent to technologies like JSP and PHP, but those pages are craving for some order and explanation comments on a large portion of the code. What I did was space code blocks and align PHP tags, the first step towards an intelligible code, but then something else came up: I couldn’t just change those files because this one tool to detect differences on files would gone useless to other developers, so I had to undo the spacing and aligning. I believe that QualDev needs to have a process in which lines of code, the core of the invisible automaton, must be easy to read, to understand; its comments, the documentation next to the LOCs have to make that possible, and those comments, those annotations, must be robust, comprehensible, written in a colloquial way on all java files, and, even more, on all artefacts possible and relevant.. QualDev: current state Currently, there are tutorials on the wiki site showing how to name classes, based on an information header in order to respect the LGPL7; there are tips on how to comment the class description; the CVS annotations with additional explanations; the class attributes and methods as well, and even though those tips are not processes at all, it helps my cause, it introduces my next pages8.. 7. GNU Lesser General Public License (http://en.wikipedia.org/wiki/GNU_General_Public_License). 8. http://qualdev.uniandes.edu.co/wikiProcess/doku.php?id=tutorials:development:development. 13.

(14) As this work focuses on coding practices and documenting practices associated with that code, lets take a look inside the code from Changeset. Taking the bean9 of image 1 into consideration, we can see it does not comply with what was written in the wiki site of tutorials.. Image 1. It does not have a class description nor its only attribute description; it should not matter if it is a serial. Of course, this class inherits from an abstract one and according to the tutorials, the description of methods and attributes should be copied and pasted from the super-class’ description. Nevertheless, on image 2, it can be noted that an implementing class does not have an exact description as the interface being implemented.. 9. Java class, according to certain conventions for being an EJB. http://java.sun.com/j2ee/tutorial/1_3-. fcs/doc/EJBConcepts4.html. 14.

(15) Image 2. The green letters mean a non-javadoc comment. Actually, all methods in that class lack a javadoc description, so do the attributes. It would be practical not to follow that particular tutorial tip, whereas a genuine javadoc @see tag10 replace those green letters. On the other hand, the code itself is not explained. Blocks of code can get pretty disorganized, and people at QualDev manage this by having a standard of indentation so as to make clearer the reading.. I believe that downloading a project from CVS and opening a random file could be compared to opening a book at a random page and start reading. Unless you do not know the subject at all, or the language (Java), you more or less understand it easily and see the relation to the next or the previous pages. In the case of software, next or previous pages can though of as the call hierarchy you can see in Eclipse; also, abstract classes and interfaces above others. And you need to know that there will always be chapters, separated by use cases, and not only functional premises of the application but the non-functional ones, critical to the stability and future life of a software system. This is where the “self-awareness of code” comes in saying you have to know exactly, given an amount of practice, what that code is doing, at what level, where and why; those little details add a lot of useful information to the entire process.. 10. See http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#javasourcefiles. 15.

(16) ESPRO As seen in the section before, a clear introduction on what the new process is going to be, I am going to talk now about how to document code and document this very task for QualDev. The goal is to create a process, according to the Specification and Documentation of processes, from now on ESPRO. In order to do so, let me define the central idea: a process to help programmers document while coding; document a class (or interface), its attributes and methods, and even configuration files or some other artefacts. Since there is a tutorial on development at the wiki site, this work will integrate parts of it and replace others. Templates, tutorials, check lists and BPMN diagrams, as said in the ESPRO definition, will validate this new process to enter QualDev’s list of processes. The possibility of a validation tool will create an appropriate atmosphere for further validation around this QualDev’s coding support process (QualDev’s CSP). Design committee conformation The first step to create a new process in QualDev is to form a committee, a sub-group in charge of the design and definition of this new process. For the case of CSP, the committee tends to be only one person and all activity definition will depend on me. Nevertheless, Difusión group is in charge of guiding this process definition and approve after meetings and revisions. Process document. 16.

(17) The second step, according to the BPMN, is to write a definition document, in which the general view of the process is presented; also, it needs to talk about the purpose, roles involved, activities and resources. That document will be presented in short, as part of this work. Support documents Next, a few documents attached to the previous one are in order. These will help consolidate the process and serve as support for implantation and information on it. The actual process will extract parts from this work, and those support documents will be included in the final version to be incorporated to the processes’ site.. Configuration management (CM) with Changeset As if it were some kind of symbolism, the final step is to administrate CSP within Changeset, taking care of identification scheme, item version management, item state management and baseline management. Once all mandatory artefact are properly made, CM will take its place.. The process Nombre Proceso de Soporte a la codificación ID PSC Descripción El proceso de soporte a la etapa de codificación está hecho para ayudar a programadores nuevos y actuales a entender código escrito de manera más eficiente y rápida y explicar y documentar código nuevo de la mano con artefactos necesarios o dependientes. El método consiste en documentar el código fuente como tal, las 17.

(18) líneas de código auténtico, de acuerdo con parámetros de relevancia de la LOC en cuestión. Para hacer esto, documentos de soporte se realizarán paralelamente a la hechura del código.. Propósito Es importante seguir un proceso bien establecido mientras se escribe código fuente, como si fuese un pequeño desarrollo en sí mismo, un proceso de desarrollo de software aparte que sigue pasos únicamente con el objetivo de lograr código fuente preciso, en detalle documentado y validado bajo ciertas métricas. Esto dado que PSC es inspirado en el modelo de Caos propuesto por L.B.S Raccoon, en el paper de 1994. Aquí el autor se enfoca en el desarrollador y propone entonces que las fases del ciclo de vida aplican a todos los niveles de la aplicación vista como el todo y sus partes. Haciendo parte de esto, PSC enfatiza la inteligibilidad de las líneas de código. Una vez el proceso ha sido implantado por primera vez, los resultados pueden ser vistos cuando un nuevo miembro en QualDev lee el código en busca de errores para depurar. Esta corrección de errores será documentada en el registro del CVS u adicionalmente en la wiki, dependiendo de los procesos del sub-grupo dentro de QualDev. Código defectuoso será corregido documentando sus LOCs, dejando que el PSC comience otra vez teniendo en cuenta una futura modificación.. Responsable Líder de desarrollo El rol principal a cargo de la implantación y delegación de tareas propias en el curso de acciones tomado al implantar el proceso. Este rol tiene que entender el proceso completamente, desde preguntas de otros roles sobre cómo implantarlo hasta como llenar las listas de chequeo y otros documentos de soporte provistas por PSC. Líder de proceso Por otra parte, este rol supervisará que las actividades y documentos producto de estas sean. 18.

(19) llevadas a cabo correctamente, y los reportes necesarios sean realizados a tiempo y adecuadamente.. Actividades. Seleccionar archivos para documentación de código. ID: SELECARCH. No. 1. Responsables:. Líder de desarrollo. Entradas:. Ninguna. Salidas:. Los campos de la plantilla PSC_SELECARCH_FORMA_InfoArchivo_DOC están llenos.. Descripción:. Esta actividad está hecha para registrar los archivos por ser documentados para saber cuáles archivos han sido documentados y hacer un seguimiento durante el resto de las actividades para mitigar propagación de errores y seguir el proceso correctamente. Ver documento de definición de esta actividad.. Recursos:. - Plantilla PSC_SELECARCH_FORMA_InfoArchivo_DOC para registro de archivos por documentar. Plug-in Metrics para Eclipse. -. Revisar archivos seleccionados. ID: REVISION. No. 2. Responsables:. Desarrollador. Entradas:. Plantilla PSC_SELECARCH_FORMA_DOC con cierta información de archivos.. Salidas:. Plantilla PSC_COMMENTREV_FORMA_DOC con información completa de los archivos.. Descripción:. Cada archivo necesita ser revisado reportando relevancia según el módulo, componente y proyecto al que pertenece; tamaño medido en líneas de código, porcentaje de esas documentadas y porcentaje de eso correcta o aceptablemente documentado. El tamaño del archivo en LOCs se hace con las estadísiticas de Metrics. Ver documento de definición de esta actividad.. Recursos:. -. PSC_SELECARCH_FORMA_InfoArchivo_DOC. -. PSC_COMMENTREV_FORMA_RevisionCodigo_DOC. -. Plug-in Metrics para Eclipse. 19.

(20) Documentar la clase, atributos y métodos. ID: DOCUCLASE. No. 3. Responsables:. Desarrollador. Entradas:. Plantilla PSC_SELECARCH_FORMA_InfoArchivo_DOC con información de archivos.. Salidas:. Plantilla PSC_COMMENTREV_FORMA_RevisionCodigo_DOC información completa del los archivos. -. Nueva versión de los archivos con documentación de clase completa: descripción de clase, atributos y métodos. Las descripciones tienen que tener un mínimo de líneas. Ver documento de definición de esta actividad.. -. PSC_SELECARCH_FORMA_InfoArchivo_DOC. -. PSC_COMMENTREV_FORMA_RevisionCodigo_DOC. -. Plug-in Metrics para Eclipse. Descripción:. Recursos:. ID: SOPORTARCOD. Documentar el código. No. 4. Responsables:. Desarrollador. Entradas:. Plantilla PSC_COMMENTREV_FORMA_RevisionCodigo_DOC con información completa de archivos.. Salidas:. Misma plantilla de entrada con información completa del los archivos.. Descripción:. PSC como tal es implantado aquí notoriamente debido a que las líneas de código son explicadas una por una, pero aquellas con importancia según la revisión. Ver documento de definición de esta actividad.. Recursos:. -. PSC_SELECARCH_FORMA_InfoArchivo_DOC. -. PSC_COMMENTREV_FORMA_RevisionCodigo_DOC. -. Plug-in Metrics para Eclipse. Revisar los comentarios. ID: COMENTREV. No. 5. Responsables:. Desarrollador, distinto a la persona que hizo los comentarios de código en primer lugar.. Entradas:. Plantilla PSC_COMMENTREV_FORMA_DOC con información correcta y 20.

(21) completa de archivos documentados. Salidas:. Plantilla de revisión de documentación de código.. Descripción:. Una vez los comentarios son hechos sobre LOCs relevantes, el tipo de lenguaje y estilo de escritura debe ser revisado y corregido si es necesario; sintaxis, normas básicas al escribir cualquier cosa debes ser tenido en cuenta: ortografía, precisión en tecnicismos, etc. La clase, sus atributos y métodos deben tener documentación correcta y completa. Ver documento de definición de esta actividad.. Recursos:. -. PSC_SELECARCH_FORMA_InfoArchivo_DOC. -. PSC_DOCSREV_FORMA_RevisionPSC_DOC. -. Plug-in Metrics para Eclipse. ID: DOCSREV. Revisar los documentos. No. 6. Responsables:. Líder de proceso. Entradas:. Plantilla PSC_SELECARCH_FORMA_DOC con información de nombres de archivos.. Salidas:. Lista de chequeo que asegura seguimiento de proceso correcto.. Descripción:. Una vez las plantillas de información de código han sido llenadas y el proceso terminado, el líder de proceso debe revisar los pasos seguidos, los documentos de soporte y llenar una pequeña lista de chequeo asegurando la calidad del proceso. Ver documento de definición de esta actividad.. Recursos:. -. PSC_SELECARCH_FORMA_InfoArchivo_DOC. -. PSC_DOCSREV_FORMA_RevisionPSC_DOC. -. PSC_COMMENTREV_FORMA_RevisionCodigo_DOC. Recursos adicionales Ninguno.. 21.

(22) Diagrama BPMN. Tutorial Ahora. ilustraré,. mediante. un. ejemplo,. en. qué. consiste. PSC. documentando un archive del proyecto Changeset. Los documentos de soporte finales de este trabajo reflejarán el trabajo de documentación del paquete changerequest 11. Primero, seleccionar los archivos. La actividad SelecArch se refiere a esto como los archivos que se quieren documentar. Para este tutorial, ChangeRequestItemBusinessDelegate.java será suficiente.. Hacer esto bien significa llenar la plantilla de información de archivos con con datos sobre los archivos. 11. co.edu.uniandes.changeset.changerequest, bajo la vista de explorador de paquetes en Eclipse.. 22.

(23) Metrics es la elección para medir LOCs en el archivo. Con esto, el porcentaje. de. LOCs. comentadas. y. comentadas. correcta. o. aceptablemente puede ser calculado. Calcular estos datos ayudan a diagnosticar cómo se venía haciendo el proceso de documentación antes de PSC y después.. Figura 6. El archivo se ve así (figura 6) antes de PSC: existen comentarios non-. javadoc generados automáticamente; no hay descripción de clase ni de atributos ni de métodos, mucho menos comentarios sobre LOCs. Ahora se pasa a la actividad 3, DocuClase, donde la documentación de clase toma lugar. Miramos la declaración de clase o interfase y explicamos tomando en cuenta las recomendaciones de Sun: la primera frase, una frase que resuma todo; en tercera persona, esto es, de modo. 23.

(24) reflexivo se habla de la clase, como el motor de distintos servicios u operaciones. Se incluye métodos más importantes, los más notables que le dan forma a ese objeto. Se pone la fecha de creación con el tag since, el autor, si se es el original, sino, solamente el nuevo tag. @codeComments; ambos tags si se es autor y a la vez “comentador”. Su métrica consta de un comentario de clase mayor a 3 líneas. De la misma manera, los atributos de clase se comentan. Pueden haber varios factores para comentar aquí: la descripción básica, tipo del atributo y razón de ser; si es estático, transiente, protegido, etc. La métrica para validar estas propiedades es más de una línea de comentarios. Se debe explicar a nuevos programadores el atributos más importante, de forma generosa. La tecnología que se usa puede ayudar mucho aquí. Un atributo como una interfase local requerida en la especificación EJB 2.0, sería bueno explicarla. Es importante que estos tecnicismos queden claros y sean ajustados a la realidad en su totalidad. Así mismo se procede con los métodos, que necesitan tener varios tags como tipo de retorno, parámetros, excepciones, comportamiento, razón de ser, etc. Una vez hecho esto, sería buena idea una ojeada en busca de errores ortográficos, incoherencias, etc. El todo de escritura siempre tiene que ser el mismo: reflexivo, en tercera persona y adecuadamente escrito en el idioma requerido. Para la actividad 4, SoportarCod, línea por línea, inclusive comentarios, se revisa el archivo, de manera que la generación del javadoc en HTML sea lo más completa y correcta posible.. 24.

(25) Ahora, comentamos el código:. -. En este archivo, empiezo hacienda una simple secuencia de teclas:. “enter-slash-asterisco-asterisco-enter“. antes. de. la. declaración de clase 33. Esto deja la descripción de clase vacía con algunos tags automáticos. El tag author se debe corregir si es el “comentador” es el autor como tal del código, sino, se utiliza un nuevo tag: @codeComments, y el nombre del “comentador”. -. Describir el código. Aquí es donde PSC pone a prueba al desarrollador en medio de código ajeno y experiencia para determinar invocaciones y su uso en cierta parte del código. Para documentar código, explicar su funcionamiento, se necesitan métodos de más de 4 LOCs, de acuerdo con Metrics, dado que esas líneas no sean triviales para usted y en general signifique algo para la clase. Métodos setter y setter no son candidatos en primera instancia; son métodos automáticamente generados por cada atributo en un bean, y que como norma cuentan con menos de 2 líneas. No obstante, si son especialmente modificados o tienen más de 3 líneas, deben ser comentados brevemente. Los demás métodos propios de un servicio u operación de un objeto deben ser comentados teniendo en cuenta más de 4 líneas significativas. La experiencia del programador puede dar a “significativas” métricas un tanto subjetivas que pueden acordarse con los demás miembros del grupo a partir de exponer ejemplos de código importante dentro de un método importante dentro de una clase.. Después de ese proceso de unos 15 minutos, mientras se entiende la clase entera y asociaciones posibles con otras clases, el archivo luce. 25.

(26) enteramente distinto (figura 7) y es una pieza de código entendible por cualquiera que sepa Java y un poco de J2EE.. Figura 7. Ahora iremos a la actividad 5, CommentRev, donde se cerciora de lo que se hizo. Aquí se buscan errores ortográficos, errores al teclear, estilo de explicaciones inconsecuentes en estilo (tono de los comentarios: coloquial, indiferente, técnico). Se tiene que ser particularmente cuidadoso con las inexactitudes técnicas y errores ortográficos: pueden obscurecer y cambiar el significado. Se deben seguir las normas del idioma nativo del proyecto: signos de interrogación, comas, puntos y comas, etc.. Usar mayúsculas al comienzo de oraciones. Al referirse a aspectos técnicos en comentarios de métodos, atributos, clase, estructuras de datos y algoritmos a través del código (patrones en atributos, especificaciones de APIs), tecnologías (J2EE, interceptadores), 26.

(27) ORM etc., se tiene que estar completamente seguro, con una pequeña consulta en libros o Internet acerca de lo que se está hablando. Es bueno aquí usar tags de referencia a URLs o a otros API, como el de Java. Un error tonto, una inexactitud o errores extensos de ortografía no harían mucho por mejorar la imagen del grupo, su credibilidad, su seriedad, formación de sus integrantes, y mucho menos caería bien para la imagen personal como desarrollador. Metrics puede ayudarnos a comentar el código: existen variables que se pueden tener en cuenta mientras se mira línea por línea. Una de ellas son los ciclos: cuando la Complejidad de McCabe12 aparece señalada en rojo en la vista de Metrics se tienen que comentar esas líneas. De hecho, aquí existe la posibilidad de reconsiderar las expresiones usadas. También, si la Profundidad de un Bloque Anidad es señalada por Metrics, comente la línea referenciada. Para finalizar, comente cada aspecto señalado en rojo en Metrics. Para la actividad 6, cada pregunta de la lista de chequeo debe ser respondida para lograr aseguramiento de calidad en el proceso. Las convenciones tomadas aquí son también explicadas para cada plantilla en la misma.. PSC: antes PSC puede caracterizarse por tener dos estadios de aplicabilidad claramente identificables: uno, en donde el proceso se aplica a archivos ya escritos, y otro en donde se aplica mientras se crean nuevos archivos para un proyecto.. 12. http://www.sei.cmu.edu/str/descriptions/cyclomatic_body.html. 27.

(28) No es difícil ver que la primera actividad, SELECARCH y su plantilla, no tienen aplicabilidad para el segundo estadio; en cambio la plantilla de revisión de código sería hecha al tiempo que se escribe el código y se da forma a cada archivo nuevo por el cual un nuevo cuadro en la plantilla se debe crear. Esto resulta en la elaboración de la entrada de la actividad 3, DOCUCLASE, donde se comienza entonces a implantar PSC.. Validation prototype After the description just given, support software for this process makes itself evident: it would help validation and it would produce accurate results, the most accurate possible after all activities. At first glance it may consist of a string-based façade and a user interface that allows validation of files already documented with prearranged parameters, the ones the process requires.. 28.

(29) So, let’s do a little software engineering.. Analysis This one is kind of a unique problem because the requirements are almost done and the problem environment is clearly defined. Context: CSP was made to support documentation of java files during the implementation phase, where the source code of the application is written. It is required for the system to validate those files after the process is applied and point out the results in the form of acceptance criteria and metrics used. The might be designed as an Eclipse plug-in with a perspective for better use after the code is written. Actors: Developers and Eclipse platform.. Use cases:. 29.

(30) Requirements: R1- Select files Indispensable Visible High priority Developer is the only actor here.. Summary: the user click a button to open a file chooser and select more than one file; by clicking on “OK” he “Enter” key, the files would be stored in the program’s memory.. Precondition: TRUE Postcondition: the program has the names of all files to be processed.. R2 – Select criteria. 30.

(31) Desirable Visible Medium priority Developer is the only actor. Summary:. the user selects whether. he wants the app to validate the file only for missing descriptions (class, attribute. and. method),. by. code. comments or by both of them.. Precondition: there are files (pointers) on the program’s memory.. Postcondition:. the program displays. the option selected and is ready to begin validating.. R3 – Validate files Indispensable Visible High priority Developer is the only actor here.. Summary: after the user selects the. files,. automatically. the. program. starts. validating. each on of them looking for certain hard-coded parameters.. Precondition: (pointers). on. there. are. files. the. program’s. a. table. memory.. Postcondition:. is. 31.

(32) displayed showing up methods with poor commenting or missing descriptions.. R4 – Display results Indispensable Visible High priority Developer. Summary: the user can see a table showing different statistics of each file.. Precondition: (pointers). there. on. the. are. files. program’s. memory and those files are already processed and stored in principal memory.. Postcondition:. a. table. is. displayed showing up methods with poor commenting or missing descriptions.. R5 – Save results Desirable Visible Medium priority Developer. Summary:. when results are. 32.

(33) displayed, an option enables the user to save the results in XML format.. Precondition: there are results in memory.. Postcondition: a file with all info about. the. files. analyzed. is. created and put in the results folder.. R6 – Add filters Desirable Not visible Medium priority Developer. Summary:. in a design by. contract style, programmers will develop new forms of validation by determining parameters and description of the new filter so hard-coded parameters change and necessary methods and resources for the new type of validation can be made and tested.. This. new. form. of. validation will manifest as an extension of R2 and R3, both visible. (user. interface). and. internally, as blocks of extra. 33.

(34) functionality inside R3. This kind of. extensionality. can. be. activated/deactivated.. Precondition: TRUE Postcondition: validation module behaves forms. accordingly of. filtering. to. new. already. registered and implemented by programmers.. Class diagram. 34.

(35) The previous requirements were made thinking of a standalone application, used in parallel with Eclipse. The same business logic,. 35.

(36) encapsulated in a single component can be used in a plug-in version, ideal for QualDev development phase purposes, but with some changes in UI and technicalities taken from PDE. The whole point behind making it a plug-in would be to mimic Metrics in exploring every Java file inside the current project and displaying a table with statistics in a new view. There would be no need for preferences to be customized by the user, just a click enabling the project for CSP; rebuilding the project would make the results table visible in a view.. Conclusions Given the amount of work put into implementation, the need for a precise and effective code, for a debug phase and an extension phases in a software system project, it becomes imperative to have a method for developing this part of the software development cycle as a particular independent process that contributes with overall documentation. The advantages are notorious: from a poorly documented file in which not even a class description nor attribute’s could be found for explanation or advise while debugging it, CSP helps build the confidence of a new developer in charge of debugging code he(she) has never touched or seen. Pretty soon developers feel nothing is missing and they can explore and retouch the file knowing exactly where and how they are changing the code.. 36.

(37) CSP also helps giving a professional and elegant form to the file, to the code itself, turning it into an educative model part of a whole functional program as it is Changeset. The validation tools might be there just to remind us that CSP must be done consciously and carefully to assure the life of code and its growing; assure also future readability and flexibility. As well as there are tools and plans for design, there has to be a methodology. beyond. ad-hoc. algorithms. or. technology-imposed. implementation of predominant problems, and CSP can be considered as so: an approximation to good programming practices given a good knowledge in general programming techniques.. Future work In the future, QualDev will have to think about coding… a lot. Technologies will unquestionably change and migration to other platforms is imminent. And migration will have to do with coding quite a bit. In the end, QualDev is not supported on double-click base-projects, it is a project itself. Hence is all about code and how is accomplished to achieve the group academic goals. The motive behind PSC is to help students get the code, so it has to be improved by researching new ways of setting up the program for validation upon different scenarios, potentially innumerable ones. Those classes and use cases must be implanted in the form of a beta program and then reformulate them. The sixth requirement emerges as the most suitable one for further research.. 37.

(38) There will be necessity of proposing slightly more rigid practices on the revision of documentation and code of activities 3 and 4, centred at the programmer’s discipline. We also are going to want the program to validate several aspects of coding: name of variables, spelling among code comments, comments on other artefacts, and some others the practice can only put at hand. The extensionality of an application will always be an ongoing issue, the constant future work. In fact, this first beta version can be integrated with QualDev ongoing work on plug-ins. It is just a matter of incorporate the core logic of the beta program inside one of the modules already done as plug-ins,. within the Eclipse plug-in group (formatting the code,. Changeset). These additional logic will be supported with the process documents and then, the program can be forgotten for the sake of new code, methods and/or components necessary for CSP to be validated as a new project inside the Eclipse Plug-in group. The Eclipse plug-in will be the last step. From there we are going to have only support and some enhancements.. 38.

(39) References -. [RAC95] Raccoon, L.B.S., “The Chaos Model and the Chaos Life Cycle,” ACM Software Engineering Notes. -. Boehm, Barry W., A Spiral Model of Software Development and Enhancement, ACM Software Engineering Notes, August 1986.. -. [RS] Roger S. Pressman, Ph.D., “Software Engineering (A practitioner’s approach)”, McGraw Hill, Fifth Edition, 2001.. -. [JS]. I. Jacobson and S. Jacobson, “ Reengineering your software engineering. process”, Object Magazine, March 1995.. -. [JG]. Jacaboson, I., Booch, G., Rumbaugh J., El Proceso Unificado de Desarrollo de. Software, 2000 Addison Wesley. -. [ACM] http://portal.acm.org/citation.cfm?id=225914. -. http://qualdev.uniandes.edu.co/mainWiki/doku.php. -. http://www.sei.cmu.edu/. -. http://www.sun.com. -. http://www.ibm.com. 39.

(40)

Figure

Actualización...

Referencias

Actualización...