On 09/17/2010 02:51 PM, Uwe Stöhr wrote:
Am 17.09.2010 07:58, schrieb Abdelrazak Younes:
- honor Abdel as author
That's not needed. I could do this myself in basically all of LyX source
code if I wanted to.
Why were I then several times forced then to add my name as author to
file I heavily modified? Why don't we have a convention how to handle
this?
I see these as acknowledgment. Except for the people reading the source
code for the first time, these author citation are not useful nor
important. What is important is the svn log. We could remove all of them
in my opinion.
- reintroduce the /// spacers in the header file because it makes it
better readable and we do this in all other inset header files
Come on! I am now once more upset with you! Please change it back! Do
you think I changed that because I had 10 minute to spare for nothing?
That you find it more readable is irrelevant. Please learn a bit about
about C++ inheritance and Doxygen.
I'm now 5 years developing LyX and nobody ever told me something about
doxygen nor have I seen a documentation in our coding guidelines.
Doxygen is used all over the code... which does not mean it is correctly
used. But you're right this should be written down in the coding guidelines.
Besides this, in my opinion readability of code is an important point.
These method are _inherited_ so the documentation for these methods are
(or should be) in the base class, not repeated everywhere. This is why
the /// add to the confusion and do not add an readability.
In general I hate that nothing is documented leading to superfluous
discussions and to code where we do things different for different
files. Take for example the fact that I wrote GuiLine as InsetCommand
and you complained why I didn't wrote this as InsetWidget. But from
where should I have got this information. I still cannot find anything
about that InsetWidget is now preferred.
True. I should add some documentation.
Moreover, why do not all Guis use InsetWidget to have some uniformity?
Because I don't have the time to migrate everything. But only those
using InsetCommandParam should be migrated.
While I'm at it, it frustrates me a lot that we don't have real code
documentation in the form to have the infos what files are doing what
(for example like I documented my installer code:
http://www.lyx.org/trac/export/35424/lyx-devel/trunk/development/Win32/packaging/AltInstaller/informations/InstallerStructure.pdf)
One always needs hours of debugging to learn what functions are called
in what files. Without my desktop search program I would be lost.
Once I learned programming at school we were forced to add at least 2
comment lines at the beginning of every routine to describe what this
routine does and in what other code regions this is used. I miss that
in LyX.
You are free to add some.
Moreover in my first commits years ago people complained that such
comments are unnecessary.
It's true that some comment are unneeded if the code itself is obvious.
In general and contrarily to what is taught in school, clear and
readable code is the first priority, comment is only the second.
Abdel.
