Ada 95 Quality and Style Guide | Chapter 7 |
7.1.3 Commentsguideline
Use highlighting comments for each package, subprogram, and task where any nonportable features are present.
For each nonportable feature employed, describe the expectations for that feature. example
------------------------------------------------------------------------ package Memory_Mapped_IO is -- WARNING - This package is implementation specific. -- It uses absolute memory addresses to interface with the I/O -- system. It assumes a particular printer's line length. -- Change memory mapping and printer details when porting. Printer_Line_Length : constant := 132; type Data is array (1 .. Printer_Line_Length) of Character; procedure Write_Line (Line : in Data); end Memory_Mapped_IO; ------------------------------------------------------------------------ with System; with System.Storage_Elements; package body Memory_Mapped_IO is -- WARNING: Implementation specific memory address Buffer_Address : constant System.Address := System.Storage_Elements.To_Address(16#200#); --------------------------------------------------------------------- procedure Write_Line (Line : in Data) is Buffer : Data; for Buffer'Address use Buffer_Address; begin -- Write_Line -- perform output operation through specific memory locations. ... end Write_Line; --------------------------------------------------------------------- end Memory_Mapped_IO; ------------------------------------------------------------------------rationale
Explicitly commenting each breach of portability will raise its visibility and aid in the porting process. A description of the nonportable feature's expectations covers the common case where vendor documentation of the original implementation is not available to the person performing the porting process.
< Previous Page | Search | Contents | Index | Next Page > |
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
TOC | TOC | TOC | TOC | TOC | TOC | TOC | TOC | TOC | TOC | TOC |
Appendix | References | Bibliography |