[Development] No implementation hints in Qt Documentation

[Thiago Macieira]

On quinta-feira, 3 de maio de 2012 22.54.38, Olivier Goffart wrote:
> On Thursday 03 May 2012 12:30:21 Thiago Macieira wrote:
> > In any case, the documentation is what's valid. If the code and the
> > documentation differ, usually the documentation prevails and the code
> > needs
> > to be changed.
> 
> I think this is an overstatement.
> If there is conflict between the documentation and the implementation, I
> rather change the documentation. Unless it is clearly a bug.
> 
> Rationale: Changing the behaviour of something might break existing
> application (remember we pretend to maintain binary compatibility).
> While a change to the documentation won't break anyone's code.

Of course, it's subjective.

But if someone reports a bug saying "it says it would do X, but it doesn't", 
usually we fix the code to match the documentation. And that's because usually 
the documentation is simply stating the principles of least surprise and of 
intuitive API.

> > I'm not saying the documentation will always be enough. But it should be
> > good enough for the vast majority of the cases,
> 
> It should.  But that implies the documentation is pefrectly written.

I said "good enough", which implies that it isn't perfect. It does have bugs 
of its own, but in the vast majority of cases it should be enough. And we 
should strive to write really, really good docs.

> > so looking into the source
> > code should not be necessary. At least, not while you're writing your own
> > code
> 
> I like to know what is under the hood when i am writing my own code. It
> helps to understand the performence penalty, and also the corenr case.
> For example, we don't document the complexity of every function.

True, but you're not our typical developer, Olivier. When I work with QString, 
I'm perfectly and painfully aware that calling indexOf might be worse than 
looking for myself. I look after data dependencies, trying to optimise at that 
level. I really doubt that most developers do that, or even care at that low-
level.

For them, the challenges are much bigger and much higher up, meaning that the 
complexity of a simple function call is often irrelevant.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
     Intel Sweden AB - Registration Number: 556189-6027
     Knarrarnäsgatan 15, 164 40 Kista, Stockholm, Sweden
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120504/3266b62f/attachment.sig>