Add comments to the source code when needed

• Nov 4, 2011 - 22:14
S5 - Suggestion


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

My brain will explode :-D





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

exemple for var

or func:
pos2() or pos()

not very explicit isn't it?

i continue my work



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, which states "Few source code comments".

Regards, Leon.

Title [Trunk] Add a little comment in source and var more "expressive" Add comments to the source code when needed
Type Functional Development
Frequency Few
Regression No
Workaround No