let's do docs.

[Alexandre Oliveira]

I still think good and obvious code is much better than docs. Some XP
classes and bad experience with docs gave me this bad perspective.

I agree on documenting to some extend, but it's something to be done
after the code is somewhat done, not something to be done while it's
still expected to change deeply, and it shouldn't ever be done before
the coding (unless you're dealing with a very big project, or when you
need to publish interfaces even before the implementation is ready, or
on some specific situations).

Anyway, I don't think we should document methods with obvious names
and that don't do anything suprising, unless they "published".
By published I mean stuff that's meant to be used by third-party.

What I think we should do is:

Don't mind about docs while building up the class, just make sure you
document all ugly hacks. After the class is somewhat stable, be sure
to write whatever is necessary. Maybe we should write doc for each
other's code, it's a great way of learning the code when the person is
available to explain, and having areas that only one person
understands is something very bad.

If it's published (like the engines, plugin interfaces, dbus
interfaces), write the docs by the book. Write docs for every detail,
don't miss a thing. Be pedantic!

if it's not, write a small description for the class, and document
only the not so obvious methods, explaining why they're necessary, and
why they do something not so obvious.
If the method's name doesn't reflect what it does, change it. While
you think the method need a comment, find out why you think it needs a
comment, and fix it if possible. Extract parts of code to other
methods if necessary, but we should end up with small methods that you
can tell what they do only by looking at their names. If it's not
possible, give up, and write the comment. (I don't mean you should
feel bad for doing it though, sometimes there's no way, or it's not
worth)
The same for member variables. No "dirt stuff" on playlist, please!

About the StatusBar, it wasn't something that we changed all the time.
Documenting the playlist like that would have taken a lot of time, or
we'd end up with outdated docs often.



On 3/19/07, Ian Monroe <ian at monroe.nu> wrote:
> On 3/19/07, Martin Aumueller <aumueller at uni-koeln.de> wrote:
> > I think we should not go overboard when writing docs and focus on writing
> > self-documenting code. Just the parts which newcomers wanting to implement
> > new plugins are most likely to use should be really documented. Amarok was,
> > and probably will be, a fast moving target. And keeping the docs up to date
> > is just too much time. And wrong docs is even worse than no docs.
>
> I disagree. Max documented his StatusBar methods and its been handy.
> And never actually out of date. Its obviously dangerous to change the
> behavior of a method enough that it'd need new documentation, so I
> think it naturally does not happen often.
>
> And we shouldn't see documentation as something for new devs, but for
> each other and for ourselves in a few months when we've forgotten what
> we've done.
>
> Ian
> _______________________________________________
> Amarok-devel mailing list
> Amarok-devel at kde.org
> https://mail.kde.org/mailman/listinfo/amarok-devel
>