On 6/16/06, Anselm R. Garbe <[EMAIL PROTECTED]> wrote:
On Thu, Jun 15, 2006 at 08:47:12PM -0400, Geoffrey Alan Washburn wrote:
> Also, just because the goal is an efficient and lean window manager
> doesn't mean you shouldn't include any comments in your code. It is
> really inexcusable to not at least have comments explaining what a
> function does, if not comments on the logic. Proper documentation would
> have saved me a lot of effort. However, given how little code is
> actually there, it is rather tempting to rewrite it in proper language.
I agree that several portions should be commented properly, but
only those which do unobvious things or which might be easier to
understand if the context is commented. Comments like
/* focuses client c. */
void
focus_client(Client *c)
{
...
}
are quite useless, because the function name already documents
its purpose. Same applies to variable names. Comments about the
logic like
/* loops 100 times */
for(i=0; i < 100; i++) {
...
}
are quite useless as well, because it is obvious what the loop
does. However, comments make sense if they describe the
context of a specific function or algorithm.
At least no comments are better than wrong or verbose ascii art
which make the code lesser readable or might be total
misleading.
You are right with that, but whenever I make somebody read you code I
get complaints about the missing documentation. So maybe you should at
least consider to document parts of it. The simple comments can savely
be left out, but *please* document what is not obvious.
--
mit freundlichen Grüßen
Steffen Liebergeld
_______________________________________________
[email protected] mailing list
http://wmii.de/cgi-bin/mailman/listinfo/wmii
