Hugin Coding Style Guide
Yuval Levy
back in August 2009 we had a discussion about coding style consistency. The
result of that discussion have been a needle in a haystack on my hard disk.
today I found it, polished it, and published it on the Hugin website at [0].
Please take a few minutes to read it and help improve it. We are all better
off if we stick to the same coding style.
Have a good week
Yuv
paul womack
> Hi Hugin developers,
>
> back in August 2009 we had a discussion about coding style consistency. The
> result of that discussion have been a needle in a haystack on my hard disk.
>
> today I found it, polished it, and published it on the Hugin website at [0].
>
> Please take a few minutes to read it and help improve it. We are all better
> off if we stick to the same coding style.
All individuals (especially coders...) disagree
on code style, but using a consensus
code style (even an imperfect one) beats the hell
out of a project with a mixture of code styles.
I did hear a claim once that a person
I worked with preferred a mix of coding (and layout)
styles, so that the coder could be easily identified.
I was speechless.
BugBear
T. Modes
On 14 Feb., 06:23, Yuval Levy <goo...@levy.ch> wrote:
> Hi Hugin developers,
>
> back in August 2009 we had a discussion about coding style consistency. The
> result of that discussion have been a needle in a haystack on my hard disk.
>
> today I found it, polished it, and published it on the Hugin website at [0].
>
>
Why do we need 2 different version of the document on 2 different
places? There is a document in the hugin doc [0] which you used as
base of your extended version. Why did you not extended the existing
version? There should only be one version. I vote for the version
inside hugins doc instead an external version.
Thomas
PS: Here the link to the existing version: http://hugin.sourceforge.net/docs/html/#code
Yuval Levy
On February 14, 2011 11:37:03 am T. Modes wrote:
> Why did you not extended the existing version?
Short answer: because Doxygen is the wrong place for this kind of document.
I know of very few projects that keep this kind of document in doxygen.
> There should only be one version.
Agree. And I vote for the one on the website.
> I vote for the version inside hugins doc instead an external version.
The website is as internal to the project as anything else.
I vote for doxygen, its ugly markup and poorly organized output to be used for
source code comments reference only.
For every other piece of documentation, including policy documents like this
one, there is a wiki; and there is a website. Both more reader-friendly,
writer-friendly, search-engine-friendly.
> PS: Here the link to the existing version:
> http://hugin.sourceforge.net/docs/html/#code
and here is the ugly markup from which it is generated
http://hugin.hg.sourceforge.net/hgweb/hugin/hugin/file/659715c139bb/src/dox/mainpage.dox
with the page stating itself that is "completely out of date".
I very much prefer http://hugin.sourceforge.net/community/coding_style/
(note that it is on the same internal website).
And the other sections in that doxygen formatted document are better placed in
the Wiki, where they have a higher chance to get updated, e.g. the build
instructions at http://wiki.panotools.org/Hugin_Compiling_Ubuntu
Yuv
Lukáš Jirkovský
I vote for the one the website too and remove it from Doxygen. I think
that the doxygen inside the source code should contain only code
documentation.
T. Modes
On 15 Feb., 00:07, Yuval Levy <goo...@levy.ch> wrote:
> Hi Thomas,
>
> On February 14, 2011 11:37:03 am T. Modes wrote:
>
> > Why did you not extended the existing version?
>
> Short answer: because Doxygen is the wrong place for this kind of document.
>
> I know of very few projects that keep this kind of document in doxygen.
>
> > There should only be one version.
>
> Agree. And I vote for the one on the website.
> Both more reader-friendly,
> writer-friendly, search-engine-friendly.
full text search. So I can search locally without the dependency on an
internet connection or a search engine.
>
> and here is the ugly markup from which it is generated http://hugin.hg.sourceforge.net/hgweb/hugin/hugin/file/659715c139bb/s...
What's ugly it's a matter of taste.
> with the page stating itself that is "completely out of date".
>
connection to read it.
Thomas
Yuval Levy
> Ok, convinced by majority.
Thank you. I suggest that we adopt a policy of using the following tools in
the following cases:
- Doxygen for everything that is *inside" the code, i.e. API documentation.
- The Hugin website for policy documents (i.e. those that change very seldom).
- The Wiki for developers documentation that is not inside the code, e.g.
architecture / design documents; file system layout description, etc.
If there is no objection, I will move the few things that are still in Doxygen
and do not belong there and reference the Wiki pages from the Doxygen dox. I
expect the Wiki to be more attractive to contributors.
> The doxygen doc has also an index and a
> full text search. So I can search locally without the dependency on an
> internet connection or a search engine.
Doxygen has its place and for references inside *commented* C++ code it is an
adequate tool. I have updated [0] and will propagate that information where
useful.
> I have the doxygen doc also locally. So I don't need an internet
> connection to read it.
We also scrape/mirror the user manuals from the Wiki locally to avoid the
internet dependency. Build instructions are already on the Wiki and we could
scrape developers documentation from there too if there is such a need. I
doubt that anybody needs to consult a policy document such as the coding style
guide as frequently as they may need to consult API references.
Yuv
[0] http://wiki.panotools.org/Hugin_Compiling_Ubuntu#Dive_into_the_Code
T. Modes
> Thank you. I suggest that we adopt a policy of using the following tools in
> the following cases:
> - Doxygen for everything that is *inside" the code, i.e. API documentation.
> - The Hugin website for policy documents (i.e. those that change very seldom).
> - The Wiki for developers documentation that is not inside the code, e.g.
> architecture / design documents; file system layout description, etc.
>
function. This links are automatically created by doxygen. But in the
wiki they need all to be created by hand. Also in doxygen I can
include small samples in which all functions/classes are links so the
reader can easily follow them to read more details (see e.g. the
example in the introduction). To create something similar in the wiki
this would require a lot of manual work.
Also it is easier to keep the doxygen in sync with the code base than
the wiki.
> If there is no objection, I will move the few things that are still in Doxygen
> and do not belong there and reference the Wiki pages from the Doxygen dox.
> I expect the Wiki to be more attractive to contributors.
tools. Here could even user contribute. But have a look who
contributed to these documents.
Thomas
Lukáš Jirkovský
>> - The Wiki for developers documentation that is not inside the code, e.g.
>> architecture / design documents; file system layout description, etc.
>>
> Here I don't agree. The developer documents often refer to classes or
> function. This links are automatically created by doxygen. But in the
> wiki they need all to be created by hand. Also in doxygen I can
> include small samples in which all functions/classes are links so the
> reader can easily follow them to read more details (see e.g. the
> example in the introduction). To create something similar in the wiki
> this would require a lot of manual work.
> Also it is easier to keep the doxygen in sync with the code base than
> the wiki.
Your opinion about not using wiki for architecture/file system layout
sounds very reasonable to me. Not only because of the point you made
but also because when you're hacking on hugin especially the
information about file layout can be handy. Therefore the possibility
of having them installed locally is certainly good from my point of
view. The case of coding guidelines is different, because you need
them only before you set formating in your editor to match the
guidelines.
Lukas
Yuval Levy
On February 16, 2011 02:36:22 pm T. Modes wrote:
> > - The Wiki for developers documentation that is not inside the code, e.g.
> > architecture / design documents; file system layout description, etc.
>
> Here I don't agree.
OK, I understand and won't proceed. I suspect we will have some overlap: the
build instructions on the wiki are more up to date and detailed than what is
in doxygen and some information is better redundant, i.e. adapted to different
target audiences.
> Also it is easier to keep the doxygen in sync with the code base than
> the wiki.
keeping in sync with the code base is a challenge regardless of the
documentation tool. As a project have not excelled particularly at the
challenge, with very few exception.
> > I expect the Wiki to be more attractive to contributors.
>
> You are too optimistic. See e.g. the documentation of the different
> tools. Here could even user contribute. But have a look who
> contributed to these documents.
When I look at the build instructions for the different platforms on the wiki,
they are pretty much a success. Many of the contributors are not coders.
Then other areas are not so successful. I stopped tracking SVN revisions that
build and that do not long time ago when nobody really used that info (the
easy test is to stop providing it and see if somebody complains).
One of the reasons why it is challenging to keep the different bits and pieces
in sync is that the contributors are different, and with different motivation.
That's OK. For example, I estimate that it has taken roughly six months for
the change from SVN to Hg to be propagated, and we probably still have some
outdated SVN references out there. And the wiki is generally well kept. When
somebody mentioned that the link to the Windows 64bit patches was broken
(after the tracker migration), it had been updated.
So far the wiki has been a great tool for attracting outside contribution.
First for building and testing; then for distribution. Why not trying for
coding? I am confident that if we add more "introduction to coding" material
we might stimulate the curiosity of the one or the other person that reads
those pages. The Ubuntu build instructions alone generated more than 75K
views. Many of them from repeated visitors, no doubts, but still a
considerable amount of traffic / people that got expose/introduced and maybe
becaome proficient in the art of building Hugin. I doubt the doxygen pages
attract as many viewers. I strongly suspect that the users who look at the
doxygen documentation have already put their hands under the hood. Describing
trivial but essential things such as file system layout on the wiki is
redundant in terms of information; but not in terms of target audience. It
helps demistify the approach.
So: I hope you will be tolerant of a little bit of redundancy. As usual,
there is no expectation of anybody to maintain what others have started.
Where there is a need there is a will; and if the need is not really there,
the pages will become outdated / obsolete with time. Which is what happened
to some of the doxygen documentation. No tool is immune.
Yuv