On Mon, Dec 15, 2008, Francisco Vila <paconet....@gmail.com> said: > I have a question for the few developers that in some degree do > understand the source code and are able to hack it, fix bugs, > implement new features, etc. > > Is the code properly commented, so that (thinking on the future) new > people can learn from it without having to figure out all the time > what does each function, file etc. do?
Newbie to the project, but one who has been programming since 1968, this is something I have discussed at length with other experience programmers. I speak in general, have yet to delve into Lp code at all, so please forgive if this is already covered by a project policy or perhaps a gnu policy. Good code commenting is a challenging skill, at its best the comments on archived code should Be accurate, uptodate, not telling lies. Explain why someone would want to invoke the code Describe context for use - arguments in, side effects, value(s) returned. Cite sources for non-trivial algorythms used, if original, publish a white paper to the project which can be cited. In many cases comments will exceed the code itself. Line-by-line comments are sometimes useful but should give information beyond the obvious. In a language like postscript the expected state of the stack is ofen a useful comment. Some projects embed text for documentation and help files with the code itself to encourage parallel maintenance. -- Dana Emery _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
