[Trunk] Add a little comment in source and var more "expressive"

• Nov 4, 2011 - 22:14
Type
Functional
Severity
S5 - Suggestion
Status
active
Project

Hello,

Can you add some comments lines in your source code :-) and var name more explicit :-) please

My brain will explode :-D

Regards

Robert


Comments

Hello,

I'am trying to learn how work musescore and it's very hard with the low number of comments

exemple for var
_userOff2
_p2

or func:
pos2() or pos()

not very explicit isn't it?

i continue my work

;-)

Gai-Luron

PS: Plus sérieusement, si tu as du temps à m'accorder pour essayer de comprendre comment fonctionne ce logiciel, cela me ferait avancer beaucoup plus vite. Pour l'instant je me limite à la partie rendu et graphique, le reste viendra plus tard. Sinon ce n'est pas grave, je peux comprendre que ton temps soit limité et je me débrouillerais seul et ... je l'aurai ;-).

With all due respect for everybody working on MuseScore (an amazing amount of code has been written, resulting in a great product), even I find it hard to understand some parts that I am not familiar with. This is after working on it since version 0.2. My experience is that although some documentation exists (developer manual and source code comments), these are quite incomplete. Many functions and variables have no comment at all, most algorithms are not documented.

I understand this results in a steep learning curve for new developers. After some familiarization it is of course a lesser issue. Having said that, I feel that we would benefit from improved documentation: it would be easier to get effective help from new programmers and it would enhance the quality of the product for end users. If the internal workings (including design, assumptions and constraints) were documented in more detail, I expect the number of bugs to decrease.

Finally, I do understand that improving the documentation also takes time, which means less time available for enhancements and bug fixes. It does however seem to me that almost all time is spent on code and very little on documentation. See also http://www.ohloh.net/p/musescore, which states "Few source code comments".

Regards, Leon.