Ada 95 Quality and Style: Guidelines for Professional Programmers Department of Defense Ada Joint Program Office SPC-94093-CMC Version 01.00.10 October 1995 Ada 95 Quality and Style: Guidelines for Professional Programmers SPC-94093-CMC Version 01.00.10 October 1995 Prepared for the Department of Defense Ada Joint Program Office Produced by the SOFTWARE PRODUCTIVITY CONSORTIUM SPC Building 2214 Rock Hill Road Herndon, Virginia 22070 Copyright 1995, Software Productivity Consortium, Herndon, Virginia. This document can be copied and distributed without fee in the U.S., or internationally. This is made possible under the terms of the DoD Ada Joint Program Office’s royalty-free, worldwide, non-exclusive, irrevocable license for unlimited use of this material. This material is based in part upon work sponsored by the DoD Ada Joint Program Office under Advanced Research Projects Agency Grant #MDA972-92-J-1018. The content does not necessarily reflect the position or the policy of the U.S. Government, and no official endorsement should be inferred. The name Software Productivity Consortium shall not be used in advertising or publicity pertaining to this material or otherwise without the prior written permission of Software Productivity Consortium, Inc. SOFTWARE PRODUCTIVITY CONSORTIUM, INC. MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THIS MATERIAL FOR ANY PURPOSE OR ABOUT ANY OTHER MATTER, AND THIS MATERIAL IS PROVIDED WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND. _________________________ Ada-ASSURED is a trademark of GrammaTech, Inc. ADARTS SM is a service mark of the Software Productivity Consortium Limited Partnership. IBM is a registered trademark of International Business Machines Corporation. VAX is a registered trademark of Digital Equipment Corporation. The X Window System is a trademark of the Massachusetts Institute of Technology. Other product names, or names of platforms referenced herein may be trademarks or registered trademarks of their respective companies, and they are used for identification purposes only. PREFACE PURPOSE * The purpose of Ada 95 Quality and Style: Guidelines for Professional Programmers is to help computer professionals produce better Ada programs by identifying a set of stylistic guidelines that will directly impact the quality of their Ada 95 programs. This style guide is not intended to replace the Ada Reference Manual (1995) or Rationale (1995) or to serve as a tutorial for the Ada 95 programming language. Furthermore, this book is not intended to be a guide for transitioning from Ada 83 to Ada 95. The reader is encouraged to consult the References for sources on these related topics. The style guide is divided into chapters that map to the major decisions that each programmer addresses when creating high-quality, reliable, reusable, and portable Ada software. Some overlap exists in the chapters because not all programming decisions can be made independently. Individual chapters address source code presentation, readability, program structure, programming practice, concurrency, portability, reusability, performance, and a new chapter on object-oriented features. Each chapter is divided into guidelines, using a format that supports wide usage because its content is both prescriptive and tailorable. Each guideline consists of a concise statement of the principles that should be followed and a rationale explaining why the guideline is important. The guidelines also provide usage examples, in addition to possible exceptions to applying the guidelines. Many of the guidelines are specific enough to be adopted as corporate or project programming standards. Others require a managerial decision on a particular instantiation before they can be used as standards. In such cases, a sample instantiation is presented and used throughout the examples. BACKGROUND The Ada Joint Program Office (AJPO) funded this style guide, which was created by merging a set of guidelines for using Ada 95 with modifications to the original Ada Quality and Style: Guidelines for Professional Programmers, version 02.01.01 (AQ&S 83) (Software Productivity Consortium 1992), developed to support Ada 83. The Ada 95 guidelines are based on the wealth of data available from the Ada 9X Project, the AJPO library, and the Ada community at large. The Software Productivity Consortium’s (Consortium’s) technical staff authored the update and the Advanced Research Projects Agency (ARPA) participated in the update effort. The preexisting AQ&S 83 presented a set of guidelines to help the programmer make disciplined use of Ada’s features. In 1992, the Consortium completed the version 2.1 update to the style guide under contract to the AJPO. The AJPO referred to that style guide as “the suggested style guide for all DoD programs.” PUBLIC COMMENT This new style guide is intended to provide a tool for both the novice and the experienced Ada programmer. To meet this objective, the Consortium directly involved both the public and the best available experts from across the Ada community. To ensure this involvement, a three-step process was defined to develop this style guide: develop a draft baseline, conduct public and expert review, and develop a final style guide. The Consortium invites comments on this book to continue enhancing its quality and usefulness. The authors will consider suggestions for current guidelines and areas for future expansion. Examples that highlight particular points are most helpful. * This material is based in part upon work sponsored by the Department of Defense Ada Joint Program Office, through the Advanced Research Projects Agency under Grant #MDA972-92-J-1018. The content does not necessarily reflect the position or the policy of the U.S. Government, and no official endorsement should be inferred. iii iv Ada 95 QUALITY AND STYLE Electronic copies of this style guide are available for downloading through the Ada Information Clearinghouse (phone: 1(800)232-4211; e-mail: [email protected]). Please direct written comments to: Christine Ausnit Software Productivity Consortium 2214 Rock Hill Road Herndon, VA 22070 e-mail: [email protected] fax: (703) 742-7200 or Kent A. Johnson Software Productivity Consortium 2214 Rock Hill Road Herndon, VA 22070 e-mail: [email protected] fax: (703) 742-7200 Please include your contact information in your comments. AUTHORS AND ACKNOWLEDGMENTS The Consortium wishes to recognize all of the nearly 100 contributors to previous versions of this style guide written to support Ada 83, including its authors, editors, and distinguished reviewers. The contributors to this version of the style guide include the authors, Ms. Christine Ausnit-Hood, Mr. Kent A. Johnson, Mr. Robert G. Pettit, and Mr. Steven B. Opdahl, and the following Distinguished Reviewers, Expert Reviewers, and Technical Advisors. Distinguished Reviewers: Mr. Bill Beckwith, Objective Interface Systems, Inc.; Dr. Norman H. Cohen, IBM TJWatson Research Center; Dr. Robert Dewar, New York University; Dr. Charles B. Engle, Jr., Department of Computer Science, Florida Institute of Technology; Mr. Jay Ferguson, NSA, Department of Defense; Mr. Ken Garlington, Lockheed Martin, Fort Worth Company; Mr. Tim Harrison, ParcPlace-Digitalk Inc.; Mr. Ed Seidewitz, NASA, Goddard Space Flight Center; Mr. S. Tucker Taft, Intermetrics Inc. Expert Reviewers: Mr. Brad Balfour, CACI; Dr. Bryce Bardin, Ada Consulting and Training; Mr. Philip Brashear, CTA Inc.; Dr. Ben Brosgol, Brosgol Consulting and Training; Dr. Michael B. Feldman, Department of Electrical Engineering and Computer Science, George Washington University; Mr. Gil Myers, NOSC ; Mr. Jim Moore, The MITRE Corporation; Ms. Eileen S. Quann, FASTRAK Training, Inc.; Mr. Richard Riehle, AdaWorks; Dr. Tim Teitelbaum, GrammaTech; Dr. Joyce Tokar, Tartan. Technical Advisors: Mr. John Barnes, John Barnes Informatics; Mr. Leslie Dupaix, OO-ALC/TISE, Hill AFB; Mr. Dave Emery, The MITRE Corporation; Mr. Magnus Kempe, Kempe Software CE; Ms. Judy Kerner, The Aerospace Corporation; Mr. Alexander Miethe, CCI; LtCol Pat Lawlis, AFIT/ENG, Wright-Patterson AFB. Thanks to the other contributors who forwarded their comments, guidelines, and examples, including Lisa Chan, Bo Sanden, Wesley Groleau, Terry D. Humphrey, Pascal Leroy, Gilles Demailly, Philippe Kipfer, Tomas Peterson, Ted Baker, Mike Dingas, Willem Treurniet, T. A. Vo, and Dave Weller. Special Thanks to the Following: Ed Seidewitz, Tim Harrison, Bill Beckwith, Ken Garlington, Tucker Taft, Chuck Engle, and Don Reifer for taking time from their busy schedules to attend the Distinguished Reviewer Technical Interchange Meetings. Mike Evans and Dan Hocking from the Army Research Lab for providing electronic meeting support at the Distinguished Reviewer Technical Interchange Meetings. Philip Brashear for rewriting Chapter 10. Mike Feldman and Brian Kallberg for their updates to the dining philosophers problem. John Barnes for providing extracts from his new book. GrammaTech, Inc., who made the new version of their Ada-ASSURED product available. The examples were formatted in whole or in part using their tool. In addition, Bobbie Troy and Mary Mallonee provided technical editing; Debbie Morgan and Lisa Smith provided word processing; and Bobbie Troy provided clean proofing. v vi Ada 95 QUALITY AND STYLE CONTENTS CHAPTER 1 Introduction............................................................................................................................ 1 1.1 ORGANIZATION OF THIS BOOK.................................................................................................