Direction of KDevelop4

[Vladimir Prus]

On Monday 12 September 2005 17:36, Adam Treat wrote:
> On Monday September 12 2005 9:08 am, Vladimir Prus wrote:
> > FWIW, when getting hold of debugger code, I really wished it has much
> > more comments! There were a lot of code which function was obvious, but
> > it's was not clear why the code is needed, and how it fits in the overall
> > picture. Generally, I never seen a piece of software with too much
> > comments, so we should strive for more comments, not less.
>
> Look, I specifically said all unobvious code should be commented.  However,
> this should be very rare.  If code is so confusing as to need this, then it
> is either not very good, hacky, or not very well thought out and should be
> refactored.

I disagree.  As I said, often the code is clear, but the motivation of the 
code is not. Say, this code in gdb reply processing:

    QCString r(buf);
    r.replace( QRegExp("\\\\000|\\\\0"), "" );

is absolutely clear, but why it's there. The answer (producing reasonable 
result for QString), is not at all obvious, and requires comment. There's no 
problem with the code, but comment is needed. I see many such cases. 

> There are simply way to many places where I have to wade through
> uninstalled header files which begin with "//this is a header file for the
> foobar class" or .cpp files with "//this is the implementation for foobar
> class" or methods which begin "//this method takes an int and bool and
> returns a QString" Absolutely unexcuseable and unnecessary.

Yes, *such* comments should die.

> I like to read code to figure out what is going on.  Reading others
> comments, although sometimes needed for particularly subtle problems, slows
> me down. Often, the comment is superfluous and could just as easily be
> understood by looking at the method/class or I'm browsing through source
> code and can't see the damn source for all the glaring comments everywhere.

The kinds of comments I most interested in do not duplicate the code. They 
explain external context/motivation for the code.

> > > 3.  A source code policy.  Currently, KDevelop's source code is
> > > atrocious. Even in the new trunk branch, we have a dozen different
> > > coding styles with some individual files having more than one coding
> > > style. This makes things very hard to read...  I think your coding
> > > style is brilliant and beautiful. It is very easy to read and clear.  I
> > > think we should adopt one coding style throughout KDevelop svn and
> > > stick to it. Pick one and stick to it. Add Kate modelines for
> > > everything and give us an astyle setting to use. BTW, the astyle
> > > settings should be made a per project plugin, because different
> > > projects people work on have different astyles...
> >
> > Again, FWIW, except for basic indent (2 or 4), I don't see any effect of
> > coding style on readability.
>
> Have a look at:
> http://websvn.kde.org/trunk/KDE/kdevelop/src/partcontroller.cpp?rev=454245&
>view=auto
> http://websvn.kde.org/trunk/KDE/kdevelop/src/main.cpp?rev=454225&view=auto
> http://websvn.kde.org/trunk/KDE/kdevelop/src/projectmanager.cpp?rev=454225&
>view=auto countless others...

Had a look. Except for mixing different indent depths (tabs count as mixing 
indent depths), there's nothing is those files that really slows me down.

> I count at least a few different coding styles in the _same_ file.  Some
> places I see tab indent.  Some places I see space indent.  Some places I
> see brackets on the same line and some I see brackets on the next line. 
> Some methods calls have spacing around the arguments, some don't.  This is
> unacceptable.  First, because if I want to modify or add to this file, I
> can't determine what is the correct coding style to use.  

Your own, I guess. Again, there should be specific base indent offset, so that 
you clearly know which nesting level you're at, but everything else is a 
personal choice.

> Second, because 
> this makes my eyes bleed.

Well, that's very subjective.

> Source code should be beautiful and self explanatory in the vast majority
> of the cases.  If it is not, then usually it needs to be refactored,
> cleaned up and given a common coding style.

I doubt that code can be self explanatory without comments. I'd go as far as 
saying that every method (even in internal headers), should document:
1. What it does
2. (for slots) when it's supposed to be called
3. (for signals) when it's supposed to be emitted

Say, GDBContoller has 'slotDisassemble'. I want to look at the method 
definition, and immediately know what it does and what signals it will 
eventually emit. I don't want to read code for that method, and then read 
code of whole GDBController::parse and GDBController::parseCmdBlock (120 
lines total) just to figure out that rawGDBDisassemle signal is emitted.

- Volodya