[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our pref
From: |
John Snow |
Subject: |
Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments |
Date: |
Thu, 14 Jun 2018 16:11:11 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 |
On 06/14/2018 06:46 AM, Peter Maydell wrote:
> On 13 June 2018 at 17:55, John Snow <address@hidden> wrote:
>> The same reasoning could be used to justify
>>
>> /* two
>> * lines */
>>
>> as it's ... actually just two lines. I think people don't seem to like
>> this much either (why? does it look 'naked' on the end?)
>
> I dislike the way it breaks up the line of stars. For me it is the
> /*
> *
> */
> shape that defines a multiline comment, and where exactly the text is
> on the RHS of it is not important to my sense of visual neatness :-)
>
Yours does look an awful lot more symmetrical once you remove the text,
yeah.
*cough* I hate the way it looks too, but C99 comments have a few things
going for them:
// A multi-line comment block like this has no extra lines and every
// line in the comment is prefaced individually which aids grep
// readability, while maintained good vertical symmetry.
I think we hate C99 comments, though? Certainly we don't use them at all
right now, so it's not a good fit.
>> It would only begin to matter terribly much if we actually decided we
>> wanted to do a doxygen-style doc generation for our internal APIs for
>> compatibility with, say, fancier IDEs than vim/emacs.
>
> We ought to do that at some point -- I had some prototype patches
> for it. Doc-comment comments always start /** on a line of its own,
> though.
>
I'd love this! I love vim/emacs, but my usage of it is not wizard-tier
and in the past when working on large C++ projects I have benefited from
the magical refactoring click-buttons, tool-tips and etc. These
operations are infrequent enough that I believe it's reasonable to not
know how to do them in traditional CLI editors. If we want to lure in
new contributors, maybe this could sweeten the pot a bit?
Rigorous, mechanically verifiable function documentation is quite nice
to have in these cases. It'd be nice in general, really. It would go a
long way to help us attract less "hardcore" developers implementing
devices and features for QEMU without such a steep onboarding curve.
Do you have a proposed standard / do we have some consensus on which
generator tool or doc format we'd most like to see in QEMU? I could put
in some elbow grease to shine up the block layer if so...
>> As it stands, we're pretty inconsistent about which exact style we apply
>> when we "document" internal functions -- sometimes we document the
>> header, sometimes the implementation, sometimes both (but differently!)
>> and always with different styles all over the place. That's the real
>> problem, IMO.
>
> IMHO -- global functions should always be documented in the header
> with the prototype, and any new global function should get a
> doc comment (I require this for code I review...) I should be able
> to read about the API your code exposes to the rest of QEMU purely
> by looking at your headers.
>
This makes sense, though the way C code is laid out makes it unfortunate
you don't get to see the same comment right beside the implementation if
that's what you're working on -- but I suppose this is why we have tabs,
multi-monitors and IDEs with tooltips.
> thanks
> -- PMM
>
- Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, (continued)
- Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Thomas Huth, 2018/06/11
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, John Snow, 2018/06/11
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Richard Henderson, 2018/06/12
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Peter Maydell, 2018/06/13
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, John Snow, 2018/06/13
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Peter Maydell, 2018/06/14
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments,
John Snow <=
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Philippe Mathieu-Daudé, 2018/06/14
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Thomas Huth, 2018/06/15
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Peter Maydell, 2018/06/15
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Markus Armbruster, 2018/06/15
Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Stefan Hajnoczi, 2018/06/13