On Tue, 5 Feb 2019 at 06:44, Markus Armbruster <arm...@redhat.com> wrote: > There are two justifiable function comment placement styles: (1) next to > definition, and (2) next to declaration if it's in a header, else next > to definition. > > The rationale for the latter is having the headers do double-duty as > interface documentation. > > The rationale for the former is consistently placing the function > comments close to the code gives them a fighting chance to actually > match the code. > > I'm in the "next to definition" camp. If you want concise interface > specification, use something like Sphinx.
I'm in the "next to declaration" camp. I don't want to have to wade into your implementation to find out what it does: document it for me in the interface, please. My standard for patches I review is "if this is adding a new function prototype in a header file, add a doc comment". thanks -- PMM
