* 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
style.
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.
--
