[Kde-pim] Re: KMime::Content::fromUnicodeString() considered harmful

[Guy Maurel]

Hello!

On Wednesday, June 22, 2011 02:05:59 PM David Jarvie wrote:
> On Wed, June 22, 2011 12:38 pm, Allen Winter wrote:
> > On Tuesday 21 June 2011 9:03:37 AM Thomas McGuire wrote:
> >> Hi,
> >>
> >> today I discovered that contrary to the documentation,
> >> KMime::Content::fromUnicodeString() does not set the content transfer
> >> encoding
> >> automatically, it needs to be done by the caller.
> >> I fixed the documentation now.
No, it is not the right way!

> It could be argued that the current method should be changed to set the
> content transfer encoding, since that is what the current API says it
> should do. There is a rule that changes to existing API for kdepimlibs are
> not allowed: is it legitimate to consider the API to consist only of the
> compilable code - doesn't the published API also include the description?
We should learn and apply a "better" way of work:
- first, write **the** documentation, diskuss about this and freeze.
  It is **what** the function/method has to do, what the user expects to get.

- second, write some code to achieve the goals described first. It might occur
  that such a discovery is found --> the code has to be corrected. If the old code
  is "interessant", then we have to defined a new API for this, not the contrary.

This way gives the oppurtunity for newcomers (such as I), to understand what
a function is doing, how a program (kmail) should work **before** readinmg a line of code.
It would also very much easier to fix a bug. 

Other meanings?
-- 
guy
_______________________________________________
KDE PIM mailing list kde-pim at kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/