Vadim Lebedev a écrit :
It is much better to have couple of
phrases of comments in free-flow format
in 2-3 lines, than a 'beautiful' comment templates on half a page, which
often make impossible to see
the comment and function body together on the monitor. ( Of course there
is another reason to use comment templates and it's name 'Doxygen' so
i'll have to live with them :(.... )
Hello Vadim,
Just wanted to point out two things about Doxygen comments:
First: if I'm not mistaken, OpenWengo project coding style says that
Doxygen comments should be in .h files, so they should not annoy you
when reading source code.
Second: if you haven't tried it, I suggest you have a look at Doxygen
source code output. It's a nice way to explore existing code (at least
it was really useful for me to get started on the OpenWengo project, and
it still is when I am wandering into parts of the code I don't know yet).
The nice thing about this output is that:
- Big Doxygen comment templates have been removed.
- All classes and methods are hyperlinked, making it really convenient
to browse from one method call to its doc and then to its implementation.
Here is a (completely random example): the implementation of
WebcamDriver::setPalette():
http://dev.openwengo.org/doxygen/openwengo/wengophone-ng/branches/wengophone-2.1/HEAD/html/_webcam_driver_8cpp-source.html#l00188
So with the time i've devised what i believe the optimal approach to
coding style rules:
1) Publicly visible files (module interface *.h for example) follow
whatever coding style rules are established for the project.
2) Internal files follows the coding style of the original author. 3)
Project coding style rules are not carved in the stone, people may
propose modifications which are accepted/rejected by majority vote.
The outcome of this approach, is that it does not hampers personal
creativity of the coders and leaves them
experimentation space, so they could learn and try new things.
So how about to try my approach for openwengo?
I see your point, but I think this method has a major drawback: when
someone needs to implement some kind of transverse change, he may have
to adjust to a different coding style for each file he edit. This is
also true for maintainers having to go through several files. In the
end, I believe a properly enforced coding style is always painful on
some particular point, but is always better than having no coding style.
Aurélien
_______________________________________________
Wengophone-devel mailing list
[email protected]
http://dev.openwengo.com/mailman/listinfo/wengophone-devel
