Documenting your programs UCL DEPARTMENT OF ELECTRONIC AND ELECTRICAL ENGINEERING Documenting your Programs Why document your programs What to include in comment lines Documenting a copied program Flow charts Unified modelling language (UML) On-line documentation Java comment lines and javadoc Copying Programs from the web Why document? You should correctly document your programs because: it is part of good programming practice, as discussed in both the Java and C courses; a significant percentage of the coursework and examination marks on programming courses may be awarded for good programming practice; it enables the markers and moderators of projects to distinguish your programs from those programs legitimately included in the project from other sources. Failure to make that distinction clearly may, at best, lead the readers, including markers and moderators, to conclude that all the programming is from external sources or, at worst, raise the suspicion of plagiarism. What should be included in the comment lines? All program source files should start with: name of the program or other program identifier; name of the author, i.e. yourself if it is a program that you have written; date on which the program was written; date of the update if you are updating the program; brief description of the purpose of the program; reference to any further documentation, e.g. a user guide, chapter in a report, web page acknowledgement of any part of the program copied (legitimately) from other sources (see below for further details of such acknowledgements). All methods or procedures should be preceded by a comment line briefly describing that method or procedure and acknowledging its source if it has been copied (legitimately) from an external source; The major sections of a program should be identified by comment lines. Any section of code, however short, whose purpose is not transparent will benefit from an explanatory comment line. Obscure coding of this type should be avoided but that is not always possible. The creation and initialisation of variables often benefits from a short comment on what they are. Documenting a legitimately copied program Using another's program/s, method/s or procedure/s without permission and/or acknowledgment is academic plagiarism and may qualify as copyright infringement. The two situations where you are most likely to meet a requirement to or would find it convenient to copy a program are: starting a project that builds on an earlier project for which several key programs have been written; finding a program, through a literature search, in text books or on the web, that does exactly what you require. It is permissible to use an existing program, in these situations, if: the coursework or project, for which the programming is required, allows you to do so. Obviously a first or second year assignment would not but, in the case of a project, it might be sensible to do so - there is no kudos in reinventing the wheel. you have the program author's permission to do so you correctly acknowledge and cite the source of the program or of any procedure or method taken from the program. Check the source code and accompanying documentation for permissions to use and/or copyright restrictions. In the case of an earlier project, discuss the matter with the project supervisor. If copying for use is allowed: Follow the conditions of use strictly. Typical conditions of use may be seen at the top of any of my own Java library programs, e.g. Db.java, or any Sun Java example program, e.g. Animator.java. This usually involves including an acknowledgement (see below) and/or retaining the copyright or permission to use paragraph in your copy. They almost always exclude copying for commercial use. Email or write to the author/s thanking them for the use of the program and give a very brief description of your use of the program. Additionally If you are including the copied program as part of your own larger program, e.g. just as one class in several in a Java application: include an acknowledgement in the documentation lines at the top of the full listing. This should be there even if not requested by the original author/s. It should either take the form required by the original authors or, if this not provided, give details of the original source (see Citing the Web above for the correct method of citing a web source); include a similar acknowledgement in the documentation lines at the top of the listing of copied program itself. This should be there even if not requested by the original author/s; the above acknowledgements and citations should be mirrored in any documentation, additional to that within the source code, describing the program. If you are including a copied method or procedure as part of your own program: include an acknowledgement in the documentation lines at the top of the full listing. This should be there even if not requested by the original author/s. It should either take the form required by the original authors or, if this not provided, give details of the original source (see Citing the Web above for the correct method of citing a web source). identify and acknowledge the copied method in the comment line/s immediately above the method; similar acknowledgements should be included if the copied method has been used as the basis of a very similar method, e.g. conversion from C to Java. An example of the documentation and acknowledgement of this type can be seen in my program FourierTransform.java; the above acknowledgements and citations should be mirrored in any documentation, additional to that within the source code, describing the program. If using the copied program as a stand alone program: ensure that the originators conditions of use are met and correctly documented and referenced; ensure that it is clear in any relevant coursework or project report that this is not your own program and acknowledge and cite the source. If it is not clear whether you may copy a program contact the authors, explaining briefly why you wish to copy their program, and ask their permission to copy their program. Flow charts A flow diagram can often facilitate a reader's understanding of your program if included in documentation additional to the source code. The web page Flow Charts gives the flow chart symbols and a simple example of a flow chart. Unified modelling language (UML) Unified Modelling Language (UML) diagrams can be very effective in the accompanying documentation to an object oriented program. Ralph Morelli uses these, to good effect, in his text book, JAVA, JAVA JAVA Object Oriented Problem Solving (2nd Edition, 2003, Prentice Hall, New Jersey, ISBN 0-13-033370-0). A full UML diagram of my Complex Class can be found on Complex UML Diagram. The corresponding on-line documentation can be found on Complex.html. Abbreviated UML diagrams would be used in constructing a UML chart. See Morelli for examples. Brief UML tutorial On-line documentation Examples of documentation, additional to the source code, can be seen in the on-line documentation that often accompanies Library programs. For examples see: my own Java Library documentation of which Keyboard Input Class is a typical class documentation page; Sun's Java documentation of which Java Math Class is a typical Sun documentation page. The Sun Java Platform comes with an application that facilitates the production of html documentation pages. See javadoc immediately below. Documentation of Java programs and javadoc Course E704 introduces the standard Java comment lines, i.e. // comment and /* comments */. However, in addition, there is a Java application that comes as part of the Java Development Kit, called javadoc, that, given appropriately written comment lines, produces on-line documentation (html file). Knowledge of javadoc is not required in either our first or second year course or for most projects involving Java but students intending to use Java extensively may care to read up on javadoc. The Sun javadoc home page is http://java.sun.com/j2se/javadoc/ and Sun's javadoc tutorial may be found on How to Write Doc Comments for the Javadoc Tool. Several Java text books include descriptions of javadoc, e.g. Deital, H.M. and Deitel, J.P., 'Java - How to Program', Appendix G: Creating HTML Documentation with javadoc, pp 1271 - 1285, 1999, 3rd Edition, ISBN 0-13-012507-05, Prentice-Hall, New Jersey. Departmental home page This page is maintained by Michael Thomas Flanagan - last update: February 2009 Department of Electronic and Electrical Engineering, University College London - Torrington Place - London - WC1E 7JE - +44 (0)20 7679 7306 - Copyright © UCL 1999–2013 Disclaimer | Advanced Search |
