guideline

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.