Timwi-
Ashar Voultoiz wrote:
Are we willing to flood our code with such comments ? I personally think it will help new developpers to come help us and let older developpers to better understand the whole software.
I, for one, support this movement.
It's certainly a good start. However, function headers are only one part -- if a function goes over many pages, individual parts still have to be documented properly, which in many cases they currently are not. I would especially like to make it a requirement that any new option in DefaultSettings.php has to be documented properly, or it will not be accepted. Often it is not trivial for others to figure out what a particular option does.
Eventually, I think all the administrative options should be accessible through a web interface, like they are with phpBB etc. For that, we really need good documentation of what they do. Similarly, the people writing the Administrator's Guide on Meta will go through the configuration file. When they see something like
$wgEnableSoap = false; # Enable SOAP interface. Off by default
the comment doesn't really tell them anything the code didn't already. What is the SOAP interface and what does it do? That needs to be documented beyond CVS comments. In comparison, my comment for the ExtraNamespace feature was:
# Additional namespaces. If the namespaces defined in Language.php and # Namespace.php are insufficient, you can create new ones here, for # example, to import Help files in other languages. # PLEASE NOTE: Once you delete a namespace, the pages in that namespace # will no longer be accessible. If you rename it, then you can access them # through the new namespace name. # # Custom namespaces should start at 100.
Granted, the actual option is more complex (an array rather than a boolean). Still, we need to explain for each option exactly what it does. When you have a good source code comment, you can copy and paste it into the CVS summary, or you can say "see diff" in the summary.
We have to build our documentation up in layers, and our code is the most basic layer. Everything else depends on it being properly commented.
We probably also should separate options which can have undesirable effects post-installation (e.g. changing $wgLanguageCode requires rebuilding all messages) from those which can be changed at any time without problems.
We have a basic dev policy at http://meta.wikimedia.org/wiki/Development_policy
Maybe that can be fleshed out a bit more and sent to anyone who applies for CVS access.
Regards,
Erik