Comments

I just came across this article from 2005 written by Jef Raskin (probably most famous for having initiated the Macintosh project at Apple) on source code documentation [1]. I agree with much of what he recommends. I have never believed that code can be “self-documenting” without comments, and generally will start writing the comments before I start the actual code. I also like some aspects of Knuth’s “literate programming” concept [2].

I do find automatic documentation generators useful, however. There aren’t a lot of solutions for modern Fortran projects though. I’ve not tried to use Doxygen, but am told that support for modern Fortran features is somewhat lacking [3]. ROBODoc is pretty good, although it does not perform any code analysis, and only extracts specific comment blocks that you indicate in the source. A brand new tool called ford is very promising, since it was created with modern Fortran in mind.

I also have an idea that the best code (including comments) should be understandable to a reasonably intelligent person who is not familiar with the programming language. Some languages (Fortran, Python) make this easier than others (C++, Haskell). There is a good article here, discussing the “beauty” of some C++ code (although I disagree with his views on comments). I was struck by the discussion on how to write functions so that more information is provided to the reader of the code [4]. The example given is this:

int idSurface::Split( const idPlane &plane, const float epsilon,
    idSurface **front, idSurface **back,
    int *frontOnPlaneEdges, int *backOnPlaneEdges ) const;

Of course, if you are not familiar with the C++ *, **, and & characters and the const declaration, there is no information you can derive from this. It is complete gibberish.  Modern Fortran, on the other hand, provides for the declaration of an intent attribute to function and subroutine arguments. The equivalent Fortran version would look something like this:

integer function split(me,plane,eps,front,back,&
               frontOnPlaneEdges,backOnPlaneEdges)

class(idSurface),intent(in)  :: me
type(idPlane),   intent(in)  :: plane
real,            intent(in)  :: eps
type(idSurface), intent(out) :: front
type(idSurface), intent(out) :: back
integer,         intent(out) :: frontOnPlaneEdges
integer,         intent(out) :: backOnPlaneEdges

Here, it should be more obvious what is happening (for example, that plane is an input and front is an output).  The use of words rather than symbols definitely improves readability for the non-expert (although if taken to the extreme, you would end up with COBOL).

References

  1. J. Raskin, “Comments are More Important than Code“, Queue, Volume 3 Issue 2, March 2005, Pages 64-65.
  2. D. E. Knuth, “Literate Programming“, The Computer Journal (1984) 27 (2): 97-111.
  3. F03/08 supporting Documentation tools, comp.lang.fortran.
  4. S. McGrath, “The Exceptional Beauty of Doom 3’s Source Code“, kotaku.com, Jan. 14, 2013.
Tagged with: , , , , ,
One comment on “Comments
  1. Stefano says:

    Dear Jacob,

    I spent some years on searching for a good Fortran documentation tool. Before Doxygen provided a baseline support for also Fortran, I have used a tool that I wrote from scratch (https://sites.google.com/site/stefanozaghi/fortrandoc): a very early version was written directly in Fortran, whereas the last was in Python. This tool was abandoned when Doxygen improved its support for Fortran, but it being a generic autodoc tool tailored mainly for C-family languages, its Fortran support is limited. I never tried Robodoc, but I guess it is very similar to Doxygen. Presently, I agree with you that the best autodoc tool for Fortran programmers is Ford: it is designed just for Fortran (mainly modern fashioned style) and its job very well.

    I am not so young as I would like to be, thus I can say to have some experience about computer science: I think that a good code MUST be a well documented code. Some languages like Python have many design specifications that impose a clean programming style (e.g. I love the imposition of Python indentation) some other not… Fortran programmers are lucky: as you said, many Fortran constructs are “self-illustrative”. Nevertheless, Fortran codes (especially codes coming from the last century…) are often cumbersome (have you may tried to understand the algorithm implemented by means of abuse of “goto” statements?) a not documented at all… but I think this is a problem of (old) Fortran programmers, not of the language itself.

    In the last years I have realized that a good code is a BEAUTY code, and a beauty code must be well documented.

    This is just my poor-Fortran-man opinion 🙂

    See you soon.

Leave a Reply

Your email address will not be published. Required fields are marked *

*