John Morris wrote:
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
I think this is what I was trying to describe. John did a much more
eloquent job of it than I did.
Here is an interesting website related to the topic being discussed on
this thread:
http://www.literateprogramming.com/
Landon
________________________________
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of John Morris
Sent: Monday, February 25, 2008 12:49 AM
To: [email protected]
Subject: RE: [Geowanking] FOSS GIS Programming Style - Different
StandardFor Source Code Comments
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
Warning:
Information provided via electronic media is not guaranteed against defects
including translation and transmission errors. If the reader is not the
intended recipient, you are hereby notified that any dissemination,
distribution or copying of this communication is strictly prohibited. If you
have received this information in error, please notify the sender immediately._______________________________________________
Geowanking mailing list
[email protected]
http://lists.burri.to/mailman/listinfo/geowanking
