Hi, * Randy Kramer wrote (2007-11-12 14:56): >On Monday 12 November 2007 01:54 pm, Joachim Lous wrote: >> > I may do that, but probably not on my first pass through the code (which >is >> > still where I am). >> >> Ah, but how will you remember next time what was difficult? :-) > >Good question. But I'm certainly not ready to put comments in the code. At >most I'd do something like add double question marks (indicating puzzlement, >surprise, or whatever) as comments. And, if I don't commit those comments, >then when I do a cvs update, I'll lose them. > >I guess I could keep a personal copy of the code with my marks in, and at some >point that is probably what I'll do, but for now I haven't seen much worth >the effort.
No, you are right there. Except for solid cases of extreme puzzlement,
a bunch of double question marks do no good.
>Hmm, I guess that's the better answer--so far I haven't seen much (in the
>comments) that puzzles me. And, as far as the code goes, there's an awful
>lot that looks greek to me, but I'm assuming I'll gradually get a handle on
>that.
Here is where you can help: If you understand a part of the code which
is uncommented or which has too little comments, write one and present
it on the list.
>I do wonder sometimes what is the proper balance between newbie and non-newbie
>comments in the sense that, it would be nice if a well intentioned Jay Random
>User could have a hope of fixing some problem he sees. But, I think the
>reality is (especially in something as complicated or more complicated than
>nedit), it takes weeks or (much) longer for even an experienced C programmer
>to know enough about the code base to make a change.
Good question. I think except for basic syntax stuff like
/* Declare int var to be used in for loop, line 45. */
int i;
there is little too dumb to comment. Free Software is read much more
often than proprietary software, and by people with much less formal
education. Every minute saved by explaining something might be a
cumulative hour spend coding.
A nice example just came up: Within a for loop some memory is
allocated to members of an array. When one of the mallocs fails, the
function returns with a failure mode, and the array must be free'ed.
Of course, the array members already allocated must also be free'ed,
which I commented like this:
/* dupTagsList[i] is unallocated, let's free [i - 1] to [0] */
for (j = i - 1; j > -1; j--) {
free(dupTagsList[j])
}
This comment hints at what's going on (free the members), which should
be sufficient for anyone reading the surrounding code; and it very
shortly describes the algorithm used.
A non-beginner wouldn't have a problem to decipher that part by
himself, it's still useful to describe my intention (in case I make an
error in the implementation) and might save even him a few seconds.
Here comes another interesting part: While writing the section above I
browsed around in the code a bit. I found that the return value of
the function in question (findAllMatches() in source/tags.c) is not
used by the single caller (findDef()), but passed-through to the
caller's caller, who, in two out of three cases, just discards it.
Nothing of this is documented, so I have no idea (without delving into
it) whether this is just an omission or somehow exactly what the task
requires.
(If I would have to fix the return value somehow, I would have to
consider six functions in two different modules. So it turns out
that this is just a case of High Coupling.)
Thorsten
--
He who passively accepts evil is as much involved in it as
he who helps to perpetrate it. He who accepts evil without
protesting against it is really cooperating with it.
- Martin Luther King
pgpPA1yn8CK3a.pgp
Description: PGP signature
-- NEdit Develop mailing list - [email protected] http://www.nedit.org/mailman/listinfo/develop
