Manual talk:Coding conventions
Contents
| Thread title | Replies | Last modified |
|---|---|---|
| Dead Links | 0 | 17:46, 8 July 2014 |
| Puppet conventions | 1 | 22:00, 26 February 2014 |
| Trailing whitespace | 7 | 00:31, 5 January 2014 |
| Release notes and bug fixes | 5 | 14:50, 1 April 2013 |
| The lisp for MW mode in emacs does not work in 23.4.1 | 1 | 00:40, 6 December 2012 |
| Standards for CodeSniffer | 5 | 07:47, 11 April 2012 |
| Dedicated pages per programming language | 0 | 18:18, 20 December 2011 |
| Documentation, even if this is MediaWiki | 8 | 01:38, 6 December 2011 |
| Globals and Top-Level Functions | 1 | 23:40, 5 December 2011 |
| eg prefix for extension config variables | 6 | 22:12, 5 December 2011 |
| ef prefix | 1 | 07:16, 5 December 2011 |
| wg prefix | 2 | 07:15, 5 December 2011 |
| Deprecate private variables and methods? | 3 | 07:11, 5 December 2011 |
| What about carriage returns between sections of code? | 1 | 07:09, 5 December 2011 |
The Section http://www.mediawiki.org/wiki/Manual:Coding_conventions#eclipse_style contains the links http://pde.dubture.com/ and http://wikidemo.formulasearchengine.com/images/MediaWiki.xml which are both dead. Where can the correct URLs be aquired (especially for the second link, to the Coding Style file for Eclipse)?
Can someone start a Puppet conventions page? Or, it's fine if we just defer to an existing Puppet style guide.
Why do we want to get rid of that section on trailing whitespace? Some newbies might not realize their text editor can be configured to get rid of it automatically.
The intention of the policy is to make it easier on people who are using text editors like Notepad++ (which I use extensively), where pressing the End key on the keyboard goes all the way to the end of the line, not to the end of last visible text. And considering removing extra whitespace is a trivial operation on almost all text editors (even Notepad++), it is an easy fix to a sometimes annoying bug.
Additionally, there is absolutely no way I will agree with removing this whitespace guideline unless there is a way to remove the goddamn red highlighting that appears all over diffs. Although even if there is a way, like I mentioned above, I don't see why we should be removing this guideline.
I think the more important question is why was it removed almost randomly without any notice or discussion?
The convention was added in this edit. It was expanded a bit in subsequent edits by Nemo and others.
The current language is pretty stupid, in my opinion. I think it gives the impression that a trailing newline in a file is a bad thing, which is obviously not true, and it provides an overbearing "don't do this" without providing any rationale for why this is problematic.
It seems there's a whole separate section about trailing newlines (as opposed to trailing whitespace). This is... a bit much. We can probably make these coding conventions less onerous.
Check out my edit. How does that wording sound?
Release notes and bug fixes
The guideline says you must add to release notes when you fix a bug, but in practice this is almost never respected, especially because with git it makes merge conflicts almost certain. Automatic updates of release notes or other variants (like herds of slaves doing it in the devs' stead) are currently just dreams.
To the few who care and watch this page: remember that release notes become even more important if you remove the bug numbers from the first line of commit messages.
See also Thread "Git release notes merge conflicts" on wikitech-l (April 2012). Several ideas for a format and automated tool have been proposed there.
However the discomfort and some people neglecting to include release notes does not justify anything. Until and unless we have a different tool, one is expected to include release notes. You'll just have to deal with it, whether you like it or not. If you don't then the change doesn't get merged (it is trivial to amend a patch and add release notes).
You claim of it being "almost never respected" is simply untrue, there are only a small number of changes from relatively few people that don't provide release notes when they should. Most people do when they should.
By the way, I don't see how Talk:Gerrit/Commit message guidelines#Bug number in commit messages is relevant? If anything, moving them from the subject to the body keep the raw git-log easier to scan. More on that over on that talk page.
I agree that release notes are important, but your "small number of changes" is just wishful thinking.
As of now there are over 350 bugs marked fixed since 1.20 was branched, and only 80 mentioned in RELEASE-NOTES-1.21 (which seems to have about 150 bullets in total)... of course it's just approximations but it seems clear that only a minority of bug fixes follow the convention.
I mentioned this topic on the thread Who is responsible for communicating changes in MediaWiki to WMF sites?, I think it bears some relevance on that matter too (but it's a separate one).
Historically we did not (and presumably still don't) include release notes for a bug fix that was introduced in the same release as it was fixed. Some of these bugs may be that sort of situation.
This should be noted in the conventions, anyway it would leave us with at least 190 bugs fixed as of now (those filed before the branching) plus 27 enhancements (requested after the branching), and 188 reports that may need or not be mentioned.
I just pasted the MW mode into .emacs for emacs 23.4.1 from ftp.gnu.org, and it did not load correctly when I tried to open MediaWiki's index.php file. I don't really know lisp, so I can't really debug what happened.
I made a couple fixes that get it working for me (Emacs 23.4.1). They are pending review.
- Checking code for a coding standard without automatic checking is very inefficient.
- There is PHP_CodeSniffer which supports a lot of PHP standards (PEAR, Zend, PHPCS, Squiz, Kohana...)
- But none of these standards are compatible with MediaWiki coding standards.
- Do MediaWiki-standard for PHP_CodeSniffer exists? May be anyone know? Сan anyone easily make it?
Yeah, I second this. The staff is working on a phpUnderControl instance, so I'm sure they will get around to this eventually.
We have stylize.php which will automagically convert code to proper standard.
Where is that? I don't see it in the maintenance directory.
If anyone is interested, I have created a very basic MediaWiki coding style and it is now hosted by the Wikimedia Fundation as mediawiki/tools/codesniffer.git
Gerrit: https://gerrit.wikimedia.org/r/#q,project:mediawiki/tools/codesniffer,n,z
To clone it:
git clone https://gerrit.wikimedia.org/r/p/mediawiki/tools/codesniffer
I've generalized this page to be a code conventions portal. Branching off specific languages to other dedicated pages. The "do as PHP unless stated otherwise" is getting old because JavaScript, for instance, is simply very different than PHP. And although the end result in syntax may be similar at times, the reasoning behind is very different. Therefor it's better to describe it in the right context with examples that make sense.
See also the Restructure MediaWiki.org-thread on Project:Current issues.
I propose merging in these guidelines to improve the quality of code documentation and increase code readability.
Sounds like a good idea.
Sounds nice, except for the part about using @since...do we really want that?
I don't see any reason not to have it, and a lot of reason to do have it. I figure it's not really possible to add it to all current code accuratly, but I'd be very nice if people just added it when writing new code.
I like almost all of your proposals, just a bit skeptical with the @since. I have noticed, you have been using this in your extensions but even if you tag something as @since 0.1 and in 0.2 the whole function changes and gets new arguments, I am not sure you would update it to @since 0.2 or add a note. One way would be using multiple @since in this case and adding a note behind that how it was different back then. Anyway, I have missed this many times in MW core, would be so much easier to keep backwards compatibility if this were documented properly! Especially for public functions but also for important constants and globals.
Go go gadget wikimerger!
This thread is over a year old...how did so many old threads get bumped?
Because of the conversion to LQT :-)
Since Manual:Global variables discourages the use of globals, this Manual:Coding conventions should encourage the use of static class members and functions in lieu of globals and top-level functions. Instead of
$wgVersion; $wgTitle; function wfFuncname() { ... }
it could encourage
class SomeClass { public static $version; public static $title; public static function funcname() { ... } }
How about using eg as prefix for extension configuration variables? Some extensions do it and I have adopted the style for my extensions as well. I find it quite handy with code completion to have all extension globals coming up fast.
It was in there for three years; see r70755 and comments. That's why you've seen other extensions do it.
I don't quite understand, so it's no longer best practice to use it for extensions? Why not?
It's not that it's not best practice, it's that it snuck into the coding conventions under the radar, people read it as gospel, and now we've got $eg and ef all over the place when nobody ever really recommended it to begin with.
You can call your config globals $the_most_awsome_variable_in_the_world if you really wanted to, it doesn't matter in a practical sense.
See also Manual:Coding_conventions#Variables.
I've seen some extension use the 'ef' prefix for global function names (presumably standing for 'extension function'). Is this a proper coding convention or some unholy bastardization? Is 'wf' or 'ef' preferred for global function names in extensions?
ef has been used since ancient times, but it's not super common now. In most cases modern style puts hook functions as static methods on a class, leaving few or no raw top-level functions to be so named.
I was wondering if there was any specific reason why the prefix 'wg' is used with global variables. I am looking at starting a project and was wondering if I should just pick a couple letters as a prefix or if there is a system I should be using to choose the letters. Thanks.
It stands for "Wikipedia Global". I'm not sure that qualifies as a system. :-)
Ok, thanks. Not sure why I didn't see that article before.
Shall we deprecate private variables and methods? They seem evil, since they make it more cumbersome to extend classes.
We're actually trying to use them in new code because they help in separating abstractions and give us better better control over proper interfaces to access data. You can't force people to uses accessor methods if they still can access class variables directly. Unfortunately, due to PHP's low entry requirements, many PHP programmers know nothing about proper OOP/OOD and produce such opuses instead.
When is it good to include blank lines? I usually include a blank line between functions, classes, etc. But is it also good style to include blank lines between, say, major code sections within a function? That leads to the question of what counts as a major section of code within a function; I find it to be a pretty arbitrary/subjective decision, and ultimately having a lot of blank lines just hinders the reader from seeing very much of the code without scrolling.
