This current discussion - how code should be commented and documented - has
hardly changed since I started my first programming job more than 30 years
ago. Languages have come and gone, but code comments and design
documentation are largely unchanged. They are as bad as ever.
I've seen a lot of poorly documented code, and I've even written some of it.
Occasionally, I see a well run project with good documentation.
Documentation isn't just code comments; it extends throughout a project,
ranging from project plans and initial concepts, to specifications and
design notes.
The way you document a project depends a lot on how you manage the project.
A lone "cowboy" writing freeware can be much sloppier than a team of people
coordinating a complex product to a fixed schedule and budget. The FOSS
community spans the entire range of projects and styles; there isn't going
to be a single solution which works for all of us.
Still, we can do a lot better than we are doing.
I'll mention some things which have worked for me over the years.
. Description of the concepts. This may seem obvious, but it is
extremely helpful to know how the project team thinks about the project.
Describe the major ideas and how they relate to each other, outline the
purpose of important modules, and explain the project's vocabulary. It's
funny how each project team creates their own way of speaking. We
continually build our own Towers of Babel.
. Graphical maps of the modules. It is time consuming to wade
through hundreds of thousands of lines of code, and next to impossible with
millions of lines. A map really, really saves time. Large projects need
multiple levels of maps. In some of the better run projects, maps played an
important role in the design process. Of course, the type of map will vary
according to the project. In the old days, we used structure charts drawn on
multiple pages of line printer paper. Today, we have modeling languages and
graphical editors. Modern maps need to represent class hierarchy and data
packaging as well as the calling hierarchy. (Somehow, I haven't jumped on
the UML bandwagon, but I may.)
. Pseudo-code comments. In my experience, the best code comments are
written as pseudo-code during the design phase. Pseudo-code describes what
is being done in human terms, without getting bogged down in the details of
the programming language. With good pseudo-code comments, you can throw away
the underlying programming code and you will still understand what the
module is doing. The comments *are* the code; our compilers just aren't
smart enough to understand them. Under each pseudo-code comment, we have the
translation to Java, C++, Perl (lisp, fortran, neliac, cms2, cobol,
assembly.). The primary purpose of the code is to be understood by the
compiler. The primary purpose of the comment is to be understood by the
human. The two should say the same thing, but they operate in different
domains.
(Here's an example of pseudo-code comments)
// Do for each Point of Interest
// Calculate the Euclidean distance to the POI
// Keep track of which POI is closest
. Module descriptions. These are pretty well accepted these days.
Each important module has comments describing what it does, what the
parameters are, and any assumptions or restrictions on how it is used. It is
helpful to include a one line description of the function, starting with the
function name. You can extract these lines and sort them to produce an
index.
So what does this have to do with FOSS? Unlike private enterprise projects,
we have access to a lot of other project's code and others have access to
ours. We are a very loose-knit community with no chance of forcing
consensus. We're not going to get things like official coding standards or
universal tools, but we may get good examples to incorporate into our own
projects. Specific tools may or may not work for us, but we can build upon
them. We can learn from each other, and the community as a whole can move
forward.
I'm definitely meandering now, but I'll add a couple thoughts.
. Our program writing tools are antiquated. Like any modern
document, programs should include pictures, diagrams, formatted text, and
even speech or video. The bulk of the "program" needs to be human readable,
and only a portion needs to be in a programming language. Today's simple
text programs and comments are unchanged from the days of punched cards. We
throw away pictures and diagrams because there is no way to enter them into
the program source.
. Programming "maps" are underutilized, mainly because they are hard
to capture and hard to maintain. We need to extend our "physical geography"
tools to the realm of "software geography". The map metaphor is powerful,
and it lends itself to searching for ideas and code as well as location.
. It might be valuable if FOSS developers would start to think in
term of project "templates", a collection of tools and documents for
specific types of projects. They might take the form of already setup tools
at sourceforge - source control, sample project plans, and tools and blogs
for communicating with a distributed community. Ideally, the environments
would be compatible with each other. As a project grows from a single
programmer to a small team to a commercially supported project, the
environment and tools would smoothly shift to the next level.
John Morris
-----Original Message-----
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of Russ Nelson
Sent: Saturday, February 23, 2008 1:02 PM
To: [email protected]
Subject: Re: [Geowanking] FOSS GIS Programming Style - Different Standard
For Source Code Comments
Landon Blake writes:
> Do you think there should be a different standard or policy for source
> code comments in code used in open source programs, in comparison to
> that used in proprietary programs?
No. Comment if it makes sense, and don't comment if it doesn't. It
NEVER, EVER makes sense to explain what the code does in a comment.
Comments are for explaining WHY code does what it does, or to explain
what the code does NOT do, because doing that would be wrong.
--
--my blog is at http://blog.russnelson.com | Software that needs
Crynwr sells support for free software | PGPok | documentation is software
521 Pleasant Valley Rd. | +1 315-323-1241 | that needs repair.
Potsdam, NY 13676-3213 | Sheepdog |
_______________________________________________
Geowanking mailing list
[email protected]
http://lists.burri.to/mailman/listinfo/geowanking
_______________________________________________
Geowanking mailing list
[email protected]
http://lists.burri.to/mailman/listinfo/geowanking
