Coding Guidelines
From ConsensusWiki
Contents |
Introduction
ConsensusWiki is built on two open-source programs: MediaWiki and phpBB3. Therefore there are in fact TWO coding guidelines that you should be familiar with. Whenever you are creating/editing code for the phpBB side of the software (ie creating/editing code within the folder /phpbb/), you should be following the phpBB Coding Guidelines. Likewise, when creating/editing code for MediaWiki, you should follow Mediawiki's Coding Conventions.
In addition to these established guidelines, the ConsensusWiki project also have conventions of their own, which you should be familiar with.
ConsensusWiki Coding Guidelines
Extensions / MODs
Where possible, ConsensusWiki will use the extension system in MediaWiki, and the MOD system in phpBB. Each system has its own conventions, which you should be familiar with:
The extension system in MediaWiki uses hooks to great effect. On phpBB, however, the hook system is very limited, and is unlikely to be sufficient for the purposes of ConsensusWiki. Therefore, there needs to be discussion on whether we should create new hooks in the phpBB core code, and commit them to phpBB development repository. This will be made clear soon.
File Structure
To keep the ConsensusWiki code separate from the code of MediaWiki and phpBB, the project will insist that all new code will be kept in their own files where possible. For more details on how this can be achieved, see Manual:File structure
Comments
Make sure that any code you create is commented. Follow the commenting conventions for MediaWiki or phpBB Coding Guidelines as appropriate. Where you are adding code to a core MediaWiki/phpBB file, make sure your comment includes the word "ConsensusWiki" so that it can be easily identified as ConsensusWiki-only code. This is not necessary within files that are created especially for ConsensusWiki.
When creating a new file for ConsensusWiki, include a full description of the file at the top, after the license (see below). You should specify what the file does, any special variables and functions that the reader should be aware of etc.
Functions
Variables
License
ConsensusWiki is distributed under a GNU General Public License (GPL), and all new files must carry this information. Each new file that is created must contain the following:
# Copyright (C) 2008 {YOUR NAME} <YOUR@EMAIL>
# http://www.consensuswiki.org/
#
# This file is part of ConsensusWiki.
#
# ConsensusWiki is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# ConsensusWiki is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with ConsensusWiki. If not, see <http://www.gnu.org/licenses/>.
