Documentation: Difference between revisions
→{{header|Fortran}}
No edit summary |
|||
Line 455:
Fortran offers no language facilities for including documentation within a programme's code. Being typically a compiled language, the details of the source file (and any documentation that it may contain) are long gone by the time the compiled code is executing. Unlike interpreted languages, it has no access to its "source code" form for self-inspection (or modification!) nor are facilities provided to attach auxiliary information to the components of a programme that might be reported at run time. A determined and diligent programmer ''could'' develop such a scheme but only by writing a lot of extra code without any special assistance from the language.
There are ''slight'' exceptions to the absence of source information in the code file. The B6700 compiler offered a pseudo text variable that contains the contents of columns 73-80 (the line sequence field)
A compiler may produce a "symbol table" identifying the names of all routines and variables, and in the older days, their addresses so that when studying a memory dump there is some hope of discovering what went wrong. But "dump snuffling" is rare these days. Similarly, a run-time error such as divide-by-zero usually elicits a message giving the memory address of the divide instruction and the report may include some indication of the line number (or source sequence field) of the statement, plus the name of the routine in which it lay.
Line 474:
REAL*8 A !Distance to the next node.
INTEGER N !Number of the current node.</lang>
Quite useful documentation could be extracted just from that. By mixing actual source statements with the commentary and extracting ''both'', inane clashes can be reduced, as in <code>CHARACTER*6 TLA !Three-character name.</code> that arose because a modification to the nature of the parameter had been made, but, while revising every routine that employed such a parameter, the programmer's consciousness faded out as soon as it saw the comment start and noted "non-Fortran source", to the puzzlement of subsequent readers. A system that extracted only the commentary part from that would not give a correct report, whereas with it known that the actual declaration would be included, there would be no longer any need to repeat its details in the comment and the comment could confine itself to expounding on meaning and usage. On the other hand, F90 introduced a verbose scheme for declarations wherein something like <code>SELECTED_REAL_KIND(6, 70)</code> might appear and copying that may well merely copy obfuscation.
Similarly, there could be a convention in the file-naming scheme whereby a code file could gain access to its source file, and with further conventions put to use, it could recognise its own commands and messages and nearby find further text with explanations or examples, etc. or indeed find its own manual and print it on request. It is ''much'' better to have one file (and to maintain synchrony within it), than to have two separate files, possibly maintained by personnel in two different departments who speak different languages. An accomplished programme might even modify its own source code, say to maintain a version number - if the source code's value matches the compiled-in value then this is the first run of the new version, so increment the counter in the source code. By keeping track of the date and time, and the timestamp of each user's last use, then a user could be advised of changes to the system since their last use. Given that the update log is also within the source file and suitably identified and timestamped.
| |||