From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43)
	id 1Logfr-0005FM-7X
	for qemu-devel@nongnu.org; Tue, 31 Mar 2009 12:18:51 -0400
Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43)
	id 1Logfm-0004cV-N6
	for qemu-devel@nongnu.org; Tue, 31 Mar 2009 12:18:50 -0400
Received: from [199.232.76.173] (port=38006 helo=monty-python.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1Logfm-0004bD-Hy
	for qemu-devel@nongnu.org; Tue, 31 Mar 2009 12:18:46 -0400
Received: from mail-bw0-f220.google.com ([209.85.218.220]:47956)
	by monty-python.gnu.org with esmtp (Exim 4.60)
	(envelope-from <blauwirbel@gmail.com>) id 1Logfm-0005H1-3h
	for qemu-devel@nongnu.org; Tue, 31 Mar 2009 12:18:46 -0400
Received: by bwz20 with SMTP id 20so2246752bwz.34
	for <qemu-devel@nongnu.org>; Tue, 31 Mar 2009 09:18:45 -0700 (PDT)
MIME-Version: 1.0
In-Reply-To: <60cad3f0903310558j554d6906q6f1244fd8a7449aa@mail.gmail.com>
References: <f43fc5580903301128y2a8432f4u6b7d9375e29a5c82@mail.gmail.com>
	<49D12392.6040107@redhat.com>
	<20090330214321.GP3795@csclub.uwaterloo.ca>
	<20090330.161514.117919654.imp@bsdimp.com>
	<20090330233853.GT3795@csclub.uwaterloo.ca>
	<761ea48b0903302259p31b13c76s4c44396b8e33166b@mail.gmail.com>
	<60cad3f0903310558j554d6906q6f1244fd8a7449aa@mail.gmail.com>
Date: Tue, 31 Mar 2009 19:18:44 +0300
Message-ID: <f43fc5580903310918g1275420eie4496fd6bc8089e@mail.gmail.com>
Subject: Re: [Qemu-devel] [PATCH] Document Qemu coding style
From: Blue Swirl <blauwirbel@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Reply-To: qemu-devel@nongnu.org
List-Id: qemu-devel.nongnu.org
List-Unsubscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/pipermail/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: qemu-devel@nongnu.org

On 3/31/09, David Turner <digit@google.com> wrote:
> Very frankly, I don't think that a coding style, even strictly applied, is
> going to make the QEMU code
> easier to understand.
>
> The real barriers to understanding are the lack of structure in the code,
> liberal use of global macros
>  scattered randomly in the source code, exceedingly liberally named
> functions, and sometimes obscure
> implementation of simple concepts (*cough* CharDriverState), cramming
> totally unrelated stuff in single
> largish source files (vl.c for the win !), and a blatant lack of
> documentation comments for a lot of subtle
>  stuff in there to explain the magic.

True enough for the comments part. There are still some areas that I
don't understand well, for example TB handling and its inherent
limitations.

Which part of the source you find subtle and magical but not commented enough?

Maybe we should use Doxygen or hxtool to combine source code and documentation.