-----Original Message----- From: Jon Cruz [mailto:jon@...18...] Sent: donderdag 24 maart 2011 4:03 To: Krzysztof Kosiński Cc: inkscape-devel@lists.sourceforge.net Subject: Re: [Inkscape-devel] Doxygen cleanup
On Mar 23, 2011, at 1:24 PM, Krzysztof Kosiński wrote:
2011/3/23 Jon Cruz <jon@...18...>:
- start with "/**"
- have the first sentence as a brief description, and be
sure to end with a period '.'
- comment a function/method in the .h and not the .cpp (if
it is in
both) ...
Documenting in the .h is contentious. My opinion is: if the
function
is defined only in the header (inline), put the docs in the header. But if it's defined in .cpp, put the docs above the definition in .cpp, so documentation changes won't trigger extensive recompiles.
Not really. It hasn't been contentious in professional development for some time now.
First it only affects incremental builds, so that mainly leaves it to potentially affecting individual developers or incremental build systems. However the latter are usually automated and happily run often, so they don't care. And for developers, one would have to pull only the doc change and no other changes. For most any project with a noticeable velocity this is a rare occurrence.
More important is that such doc-only changes are extremely rare (perhaps once a quarter, if even that frequently). On the other hand the .h file is the public documentation of the corresponding compilation units, and should be kept in sync. One should be able to read just the .h and know how to use the code. Modularity and encapsulation are key to good modern software development (Brooks explains this well in his 20-year follow up to The Mythical Man Month), and keeping the .h to declare and the .cpp to define are main contributors to good encapsulation. Sacrificing things such as legibility and maintainability for the rare boost to odd builds is usually not worth it.
On the other hand, docs should be updated each and every time functions and methods change. Having them right next to each other aid in this maintainability and overall legibility. Professional developers have also found that having doc comments in the .cpp files leads more often to them becoming stale and outdated.
Also, a function or method declaration is a promise to others about the behavior of the code. Formalizing such promises with corresponding documentation is a very good thing. Developing habits to formalize promises early and to avoid arbitrary changes to the substance of a promise is also a very good thing.
I think comparing Inkscape development with professional development is quite a stretch. Even if people are going to document stuff in Inkscape, it is most probably done incrementally (like much else), because it is more 'fun' this way. And I really hope nobody is going to start documenting verbs.h incrementally. I have additional arguments in favor of putting comments in the .cpp files. For me, it helps sometimes to see the documentation of a function next to its code; helps noticing bugs. While comments in a header file sometimes bloat the file and make it pretty hard to find a method that I want to call (sp-object.h is a horrible read, whatever experts say, I don't like it). The good thing about us using doxygen syntax is that... one can run doxygen (!) and read comments in a reader friendly interface. So one really shouldn't look at the code files to read documentation, right?
Ciao, Johan