From kde-devel  Wed Jul 31 23:59:16 2002
From: Tim Jansen <ml () tjansen ! de>
Date: Wed, 31 Jul 2002 23:59:16 +0000
To: kde-devel
Subject: Re: comment style
X-MARC-Message: https://marc.info/?l=kde-devel&m=102815912023717

On Thursday 01 August 2002 00:57, Henry Miller wrote:
> Perhaps I should put it this way: if/when I submit a patch should I put
> excess comments in it?   Is there a prefered way to document code that
> I'm missing?  Or is the belief in self-documenting code so strong that
> comments are discouraged?

I dont think that there is a general philosophy in KDE, this depends on the 
individual programmer. 

IMHO well-written code is enough, too many comments just make the code more 
difficult to read. You dont need to repeat the functionality in another 
language unless there is something hidden that's not obvious - for example a 
work-around for a bug in library, or a side effect in a function. It can be 
useful to document data structures though, because it makes extending the app 
easier (especially when the content or validity of a variable depends on a 
state). 

Documenting APIs is a very different issue, because it allows programmers to 
use the functionality without understanding the implementation. And in larger 
projects it can also make sense to offer internal APIs.

bye...

 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<