coding style - hugin and other free panoramic software

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion coding style
Received-SPF: pass (google.com: domain of l.jirkov...@gmail.com designates 74.125.78.148 as permitted sender) client-ip=74.125.78.148;
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=dG9esILsXJBTxrlUW69W4JoaP2eQ9JRZAXIYw3RN27VIkuNBIAgt9fFzdXEQyMEWnS
         F7M0CNft3VV1DSJJaUNDxFooMJKuqoP4zzEuPZAJkQL1Riv1n6MdIhX1cRL/2+qufRv+
         Lz8lfEnhHuUv8yTCddC8G7+xQxqYu77sYKz4M=
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
In-Reply-To: <4A790F38.6040008@levy.ch>
References: <4A790F38.6040...@levy.ch>
Date: Fri, 7 Aug 2009 09:43:23 +0200
Message-ID: <736420110908070043g2be701efsc0e1909e94973...@mail.gmail.com>
Subject: Re: [hugin-ptx] coding style
From: =?UTF-8?B?THVrw6HFoSBKaXJrb3Zza8O9?= <l.jirkov...@gmail.com>
To: hugin-ptx@googlegroups.com

2009/8/5 Yuval Levy <goo...@levy.ch>:
>
> * if you're not interested in Hugin's development, you can stop reading n=
ow*
>
> Hello Hugin developers,
>
> I've been looking at our source code and I find that it can use some
> consistency / clean up. The current status is historically grown - I am
> not sure every contributor has seen Pablo's notes [0] and I think our
> coding style belongs on the web, maybe on a wiki page?
>
> I would like to reach a consensus amongst the developers of what coding
> style we want. The consensus coding style should become a very strong
> recommendation for new code (I don't feel like policing volunteers /
> mandating it, but if we start to see unreadable code in commits we'll
> have to discuss it because this is critical for the project's long term
> viability); and when developers go over existing code, they can
> optionally make it more readable for themselves and for those coming
> after them.
>
> Do we want a loose coding style guideline like [1]? or a strict one like
> [2]? I tend for a loose - define a necessary minimum and let the good
> common sense of each individual contributor prevail.

I like more loose coding style. Spending a day learning what to do and
what not to do is IMO boring.

>
> Below are different points for discussion. If I have forgot one that you
> deem important in coding style, please add it. For every point there are
> a few alternatives. I have surely missed on alternatives and variations,
> so if you think that more should be added, do it.
>
> I kindly ask you to express your opinion to each and every single point
> as a contribution to the discussion. After most committers have
> expressed their opinion I will summarize the choices and propose a
> coding style for adoption.
>
>
> 1. NAMING CONVENTIONS
>
> 1.1. PRIVATE VARIABLES
>
> all private variables should have a prefix. Many (but not all) private
> variables are currently prefixed with m_ and I suggest to retain this
> style consistently across the codebase.

I don't know what to say about this. I'll be OK with it if it become a
part of coding guideline either doesn't.

>
> 1.2. VARIABLE NAMES
>
> some variables are named with the CamelCase convention - capitalizing
> the beginning of the word. Other use the word_separated_by_underscore
> convention. Are there other conventions? Which one do you favor?
>
> variable names should be clear and descriptive. no contractions, maybe
> with a few listed exception, e.g. Pano instead of Panorama. Any more
> exceptions?

I prefer camel case. But as I'm thinking about it I like convention
where classes and structures are with capitalized first word and
variables and functions are with small first word. For constants I'm
not really decisive but all caps may be a bit better because it's more
visible that it's a constant.

>
> 1.3. FUNCTION NAMES
>
> should functions follow the same conventions as variables? or a
> different one?
>
> function names should be descriptive. no contractions, maybe with a few
> listed exception, e.g. Pano instead of Panorama. Any more exceptions?

dtto.

>
>
> 2. COMMENTS
>
> 2.1. DOCUMENTATION (copied verbatim from Pablo)
>
> document your code (or the code you are reading and understanding) with
> doxygen (http://www.doxygen.org). Doxygen is a useful tool and can also
> be used to create other documentation that just class interface
> descriptions. It works by prefixing the function prototypes with a
> special comment. Pablo usually puts the documentation in the header files=
.
>
> =C2=A0 =C2=A0 =C2=A0 The basic usage is very javadoc like:
>
> =C2=A0 =C2=A0 =C2=A0 /** One sentence class description
> =C2=A0 =C2=A0 =C2=A0 =C2=A0*
> =C2=A0 =C2=A0 =C2=A0 =C2=A0* =C2=A0more detailed description
> =C2=A0 =C2=A0 =C2=A0 =C2=A0*
> =C2=A0 =C2=A0 =C2=A0 =C2=A0* =C2=A0@todo pet the cat more often
> =C2=A0 =C2=A0 =C2=A0 =C2=A0* =C2=A0@bug =C2=A0might scratch if annoyed
> =C2=A0 =C2=A0 =C2=A0 =C2=A0*/
> =C2=A0 =C2=A0 =C2=A0 class Cat
> =C2=A0 =C2=A0 =C2=A0 {
> =C2=A0 =C2=A0 =C2=A0 public:
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 /** hunt food
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0*
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0* =C2=A0@param prey type of anim=
als that we should hunt
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0* =C2=A0@return true if the cat =
is sated
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0*/
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 bool HuntFood(Prey prey);
>
> =C2=A0 =C2=A0 =C2=A0 }
>
> 2.2. WORK IN PROGRESS
>
> if something needs work, put a // FIXME or // TODO comment so that a
> grep will reveal places that needs attention. Gedit automatically
> highlights TODO and FIXME.

I'm already using that and IMO it's very useful. Quite a lot of IDEs
have some facility to search for TODO's and FIXME's.

>
>
> 3. SPACING AND INDENTATION
>
> 3.1. BRACES
>
> there are many different indent styles [3]. I am personally used to 1TBS
> [4] (like the Linux Kernel), but I recently heard good arguments to
> adopt Allman style [5], which puts the brace associated with a control
> statement or a function on the next line, indented to the same level as
> the control statement. I am ready to go Allman. Or maybe you want to
> suggest other alternatives? Which one do you prefer?

1TBS. It's very compact.

>
> 3.2. TABULATORS
>
> use spaces instead of tabulators (to maintain consistency across
> editors). use four spaces for one indentation. or are there other
> preferences?

Certainly spaces.

>
> 3.3. SPACES
>
> I would not go into that much detail. or maybe we should adopt/adapt a
> strict coding guide like [2]?
>
> 3.4. LINE ENDS
>
> Unix/Linux line ending (Windows and OSX users have to adapt)

No problem for me ;-)

>
>
> 4. COMMITTS
>
> It is tempting to clean up old code while fixing bugs or adding new
> code. Please don't - it makes the committ (diff!) much more difficult to
> read / understand.
>
> Keep style clean up committs separated and mention them as such in the
> log message.

Yep, this is good. I think everyone sane already uses this ;-)
Searching for a mistake int patch with mixed bug fixes and new code is
horrifying.

I'd like to also mention that I'm against changes to the code style
now, because it would make merging GSoC branches from even harder.

>
> I think that's about it, but I may be missing something. time to hit the
> pillow.
>
> Yuv
>
>
>
> [0]
> <http://hugin.svn.sourceforge.net/viewvc/hugin/hugin/trunk/src/dox/mainpa=
ge.dox?view=3Dmarkup>
> [1]
> <http://developer.gnome.org/doc/guides/programming-guidelines/code-style.=
html>
> [2]
> <http://www.blender.org/documentation/intranet/conventions/codingstylegui=
de.html>
> [3] <http://en.wikipedia.org/wiki/Indent_style>
> [4] <http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS>
> [5]
> <http://en.wikipedia.org/wiki/Indent_style#Allman_style_.28bsd_in_Emacs.2=
9>
>
> >
>

Lukas
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
