Fortran代码注释风格

好习惯往往意味着高效率. 编写算法程序很重要, 代码注释也是非常重要的一方面, 否则一段时间之后就该头大了. 下面给出了一个求解线性方程组的模块注释示例, 这里只包含一个简单函数—-Jacobi迭代, 注释的风格主体源自LAPACK包(拿来主义:-)).

  • 模块的注释. Fortran语言中的模块(Module), 类似于C语言中的库文件加头文件, 所以两者的注释完全可以采取类似的形式.  模块中一般要注明目的(Purpose), 全局变量(Parameter), 例程(Routines)等内容, 这样无论自己还是他人看的时候都会感觉清晰明了.
  • 例程的注释. 例程(函数)的注释完全可以移植到任何一个结构化编程语言, 一般要注明目的(Purpose), 参数(Parameter), 最好在最前面标明参数的类型, 方便快速查看.
module ls
!
! -- MODULE LS Linear-System (version : 1.1) --
! Written by : Numanal
! Date : 2015-05-16
!
! Purpose
! =======
!
! To Sovle Linear-System A * x = b.
!
! Parameter
! =========
!
! ls_IMAX (INTEGER) maximum number of iterations
! ls_TOL (DOUBLE PRECISION) tolerance for stop iterations
!
! Routines:
! =========
!
! 1. subroutine Jacobi( A , b , x , N )
! 2. ...
! 3. ...
!
!------------------------------------------------------------------
implicit none
integer,parameter::ls_IMAX=1e+6
real*8,parameter::ls_TOL=1e-7
!==================================================================
contains
!==================================================================
subroutine Jacobi( A , B , X , N )
!
! -- LS routine JACOBI (version : 1.1) --
! Written by : Numanal
! Date : 2015-05-16
!
! .. Scalar Arguments ..
! INTEGER N
! ..
! .. Array Arguments ..
! DOUBLE PRECISION A( N, N ), X( N ), B( N )
! ..
!
! Purpose
! =======
!
! JACOBI computes the solution to a real system of linear equations
! A * x = b,
! where A is an N-by-N matrix and x and b are N vector.
! To compute A * x = b given an initial approximations X, so X
! must have been valued!
!
! Arguments
! =========
!
! A (input) DOUBLE PRECISION array, dimension (N,N)
! the N-by-N coefficient matrix A.
!
! b (input) DOUBLE PRECISION vector, dimension (N)
! the N vector of right hand side vector B.
!
! x (input/output) DOUBLE PRECISION vector, dimension (N)
! On entry, an initial approximations X
! On exit, the solution of the linear Equations
!
! N (input) INTEGER
! The number of linear equations, i.e., the order of the
! matrix A. N >= 0.
!
! =========================================================
real*8,intent(in)::A(N,N),b(N)
real*8,intent(inout)::x(N)
integer,intent(in)::N
integer::i,cnt ! count iteration
real*8::norm ! norm = ||x-xx||
real*8::xx(N) ! Be used to iteration
xx=x
do cnt=1,ls_IMAX
    ! The main progress of Jacobe method
	do i=1,N
        	x(i)=(A(i,i)*xx(i)-dot_product(A(i,:),xx)+b(i))/A(i,i)
	enddo
        ! compute 2-norm ||x-xx||
        norm=0.0d0
        do i=1,N
        	norm=norm+abs(x(i)-xx(i))
        enddo
        ! if ||x-xx|| is small enough, then exit
        if(sqrt(norm).LT.ls_TOL)then
        	!print*,'iteration ',cnt ! print the count of iteration
        	exit
        endif
        ! else exchange x and xx, continue iteration.
        xx=x
end do
! if cnt is too large,i.e., the method failure
! then stop program.
if(cnt.ge.ls_IMAX)then
	print*,'fetal error :'
	print*,'routine JACOBI (in ls) Failure!'
	print*,'The program has stoped.'
        stop
endif
end subroutine Jacobi
!==================================================================
end module ls