Tuesday, October 18, 2005

Why you want to write api docs

Writing code for the kde libraries is not like writing a class that goes in your KMyBigApp. Once it gets into kde's libraries it will have the following:
  • The structure of the class can't be changed much.

  • A lot of people will (try to) use your class.

  • A lot of people will read your documentation and curse at you if it makes no sense

  • A lot of people will read your code

  • Every stupid bug will be found such as calling foo() crashes the class every time or never returns the correct result.

  • The person hiring you for your next job might look at it. (actually these days it is pretty much guaranteed they will Google for some of your code).

What am I really saying? Writing documentation (and tests) for classes in kdelibs is very much about personal pride. It isn't just a class in your application, you know that people will look for documentation, use every function, and use it in a way that you never thought of. If you have no documentation then you will have people annoyed at you. If you don't write a test application that minimally calls every function the moment someone else does and breaks your class you will feel stupid. If you take the time to write some documentation and test application you are forced to think about your class and how it best fits into a larger application. Once you do this you will discover a few things to tweak in the structure to make it better. Writing documentation and tests for a class in a library isn't busy work that you don't have time for, it is professionalism.

And if you have no professionalism you can always fall back to: Those who submit new classes today to kdecore-devel with docs and tests get a big thank you (from me and others), and those that don't have docs get rejected, it is part of the kde policy.

No comments:

Popular Posts