* MARK CALLAGHAN <mdcallag@stripped> [09/03/17 16:32]:
> Comments in the header file describe the interface. Comments in the
> source file provide more detail on the implementation. The interface
> should be less likely to change over time.
During "old style" -> doxygen transition, we agreed that comments
will be in front of definitions, not declarations, to minimize
merge hassle, and preserve BK history.
Another reason to put a comment in front of definition was that it
makes it more likely to be updated when the definition changes.
A lame argument perhaps.
Changing that now is quite significant -- we have a lot of
comments that will need to be moved.
I agree it makes it counter-intuitive for someone who's new to our
code. This way of commenting code is documented in the coding
If you would like to change it, please don't hesitate to send a
proposal -- only please keep in mind, the submitter is responsible
for carrying it out :).
If you ask for my opinion, I have none -- I don't worship the
revision history, but at the same time I can find my way in the
sources, so I can live either way.