< Free Open Study > |
cc2e.com/3208 In addition to the IEEE standards, numerous other resources are available on program documentation. Spinellis, Diomidis. Code Reading: The Open Source Perspective. Boston, MA: Addison-Wesley, 2003. This book is a pragmatic exploration of techniques for reading code, including where to find code to read, tips for reading large code bases, tools that support code reading, and many other useful suggestions. cc2e.com/3215 SourceForge.net. For decades, a perennial problem in teaching software development has been finding life-size examples of production code to share with students. Many people learn quickest from studying real-life examples, but most life-size code bases are treated as proprietary information by the companies that created them. This situation has improved dramatically through the combination of the Internet and opensource software. The Source Forge website contains code for thousands of programs in C, C++, Java, Visual Basic, PHP, Perl, Python, and many other languages, all which you can download for free. Programmers can benefit from wading through the code on the website to see much larger real-world examples than Code Complete, Second Edition, is able to show in its short code examples. Junior programmers who haven't previously seen extensive examples of production code will find this website especially valuable as a source of both good and bad coding practices.
cc2e.com/3222 Sun Microsystems. "How to Write Doc Comments for the Javadoc Tool," 2000. Available from http://java.sun.com/j2se/javadoc/writingdoccomments/. This article describes how to use Javadoc to document Java programs. It includes detailed advice about how to tag comments by using an @tag style notation. It also includes many specific details about how to wordsmith the comments themselves. The Javadoc conventions are probably the most fully developed code-level documentation standards currently available. Here are sources of information on other topics in software documentation: McConnell, Steve. Software Project Survival Guide. Redmond, WA: Microsoft Press, 1998. This book describes the documentation required by a medium-sized businesscritical project. A related website provides numerous related document templates. cc2e.com/3229 http://www.construx.com. This website (my company's website) contains numerous document templates, coding conventions, and other resources related to all aspects of software development, including software documentation. cc2e.com/3236 Post, Ed. "Real Programmers Don't Use Pascal," Datamation, July 1983, pp. 263 265. This tongue-in-cheek paper argues for a return to the "good old days" of Fortran programming when programmers didn't have to worry about pesky issues like readability.
|
< Free Open Study > |