[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: comment style
From:       Tim Jansen <ml () tjansen ! de>
Date:       2002-07-31 23:59:16
[Download RAW message or body]

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 <<
[prev in list] [next in list] [prev in thread] [next in thread]