Manual talk:Coding conventions

Jump to navigation Jump to search

About this board

For discussion about PHP coding conventions prior to August 2020, see Manual talk:Coding conventions/PHP/Archive.

Krinkle (talkcontribs)

I've proposed at T253461 that we phase out our AtEase library in favour of PHP's regular error suppression methods.

Based on the feedback gathered on the task so far, I think it's preferred that we continue to generally discourage use of error suppression (regardless of whether through @, AtEase, or error_reporting).

As such, I proposed that we keep the conventions mostly as-is, including that our PHPCS rule warns against use of the @-operator. What would change is that we'd use that same PHPCS rule as our way of opt-ing to it as-needed.

Currently:

use Wikimedia\AtEase\AtEase;

AtEase::suppressWarnings();
$content = file_get_contents( $path );
AtEase::restoreWarnings();

Now:

// phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
$content = @file_get_contents( $path );
Krinkle (talkcontribs)
Reply to "Liberate the @ for AtEase"

Dedicated pages per programming language

1
Krinkle (talkcontribs)

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.

קיפודנחש (talkcontribs)

i think it is sorely missing. User:Anomie ? or does it exist somewhere else?

peace.

Anomie (talkcontribs)

There isn't one, as far as I know. The convention generally follows mw:CC, and some bits extrapolated from mw:CC/PHP and mw:CC/JS (e.g. lowerCamelCase function names).

I wouldn't be opposed to a Manual:Coding conventions/Lua, if there's stuff that needs to go in it.

What about carriage returns between sections of code?

2
Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as Tisane.

Peachey88 (Flood) (talkcontribs)

Pretty much as you say: they're good, but should be used sparingly; it's much easier to say "apply common sense" than to try and legislate for it.

This post was posted by Peachey88 (Flood), but signed as Happy-melon.

Deprecate private variables and methods?

4
Peachey88 (Flood) (talkcontribs)
Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as MaxSem.

Peachey88 (Flood) (talkcontribs)

Protected seems preferable, for extensibility purposes.

This post was posted by Peachey88 (Flood), but signed as Tisane.

Peachey88 (Flood) (talkcontribs)

It depends. Public, private and protected all have their places. Some times you want something private because you /don't/ want subclasses to be able to change the implementation.

This post was posted by Peachey88 (Flood), but signed as ^demon.

Documentation, even if this is MediaWiki

9
Peachey88 (Flood) (talkcontribs)
Peachey88 (Flood) (talkcontribs)
Peachey88 (Flood) (talkcontribs)

Sounds nice, except for the part about using @since...do we really want that?

This post was posted by Peachey88 (Flood), but signed as Jack Phoenix.

Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as Jeroen De Dauw.

Danwe (talkcontribs)

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.

Peachey88 (Flood) (talkcontribs)
Krinkle (talkcontribs)

Go go gadget wikimerger!

Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as Imperator3733.

Peachey88 (Flood) (talkcontribs)
Peachey88 (Flood) (talkcontribs)
Peachey88 (Flood) (talkcontribs)

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?

This post was posted by Peachey88 (Flood), but signed as Kaldari.

Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as Brion VIBBER.

eg prefix for extension config variables

7
Peachey88 (Flood) (talkcontribs)

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.

This post was posted by Peachey88 (Flood), but signed as Danwe.

Reach Out to the Truth (talkcontribs)

It was in there for three years; see r70755 and comments. That's why you've seen other extensions do it.

Danwe (talkcontribs)

I don't quite understand, so it's no longer best practice to use it for extensions? Why not?

😂 (talkcontribs)

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.

Danwe (talkcontribs)

So what would be the way to get it back into coding conventions in a proper way? Doesn't seem that bad and more consistency in extension development wouldn't harm I guess.

😂 (talkcontribs)

Extensions should just use $wg, like core.

Krinkle (talkcontribs)

The lisp for MW mode in emacs does not work in 23.4.1

2
68.5.79.97 (talkcontribs)

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.

Mattflaschen (talkcontribs)