Manual talk:Coding conventions

Manual:Coding conventions/PHP#cite_note-3

...currently leads to a task with access restrictions. If it doesn't contain any sensitive information, is it possible to make it public -- and if it does, is it possible to convey the relevant information within it in another way? Friendly ping to Lucas Werkmeister (WMDE), as you added the section in question :) Best, a smart kitten[meow] 14:58, 14 January 2025 (UTC)

@A smart kitten This is now done. Taavi (talk!) 04:45, 15 January 2025 (UTC)

Does the convention about not using empty() still apply?

In a recent patch, we were using empty() for checking if an array was, well, empty, but switched it to count( $value ) > 0 due to this convention ("The empty() function should only be used when you want to suppress errors"). However, after doing so, SonarQube complained about not using empty() in this case (the error was Use empty() to check whether the array is empty or not.). So I suppose this convention may no longer apply, or the Sonar config needs to be updated? HArroyo-WMF (talk) 10:06, 18 June 2025 (UTC)

In general, you should trust human-written documentation over SonarQube, which isn't configured with our policies but instead some upstream point-of-view of what they think code should look like, sadly. I believe it still holds. Jdforrester (WMF) (talk) 14:57, 18 June 2025 (UTC)
That makes sense, thank you HArroyo-WMF (talk) 16:20, 19 June 2025 (UTC)
Actually, there’s a much simpler solution, which is hopefully not flagged by SonarQube either: $value !== []. Since PHP arrays are compared by value, an array is unequal to [] if and only if it’s non-empty. (The coding convention suggests !!$value – which is equivalent to (bool)$value –, but doesn’t discourage $value !== [] either, and I think it’s more expressive if you know you’ll only handle arrays, never nulls, boolean values etc.) —Tacsipacsi (talk) 16:28, 23 June 2025 (UTC)

Readonly properties

PHP properties correspond to the following grammar in PHP 8.1 (a bit simplified):

property-declaration:
 property-modifiers-var type-without-staticopt property ";"

property-modifiers-var:
 property-modifiers
 "var"

property-modifiers:
 property-modifier
 property-modifiers property-modifier

property-modifier:
 "public"
 "protected"
 "private"
 "static"
 "readonly"

[...]

The order of the individual property-modifiers is insignificant. The first three cannot appear together, but they can be combined with either of the latter two, so all these declarations are legal:

<?php
class Foo {
	// PHP 7.4+
	public static int $bar;
	static public int $baz;

	// PHP 8.1+
	public readonly int $a;
	readonly public int $b;
	public function __construct(
		private readonly int $x,
		readonly private int $y,
	) {}
}

PER-CS 2.0 only allows $bar, $a, $x, similarly its predecessor PSR-12 only allows $bar (PSR-12 was written before PHP 8.1, so it doesn’t discuss readonly). Our coding conventions allow everything, since they don’t discuss this matter at all. Shouldn’t we also prescribe the order for consistency? —Tacsipacsi (talk) 17:27, 23 June 2025 (UTC)

Don't add type declarations for big legacy classes

Manual:Coding conventions/PHP#Don't add type declarations for "big" legacy classes

Context: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/MassMessage/+/1148607/2..5/includes/Job/MassMessageJob.php#b47

So just to double check, I'm never supposed to use types like Title ever in PHP code? Not for class variable declarations, not for function/method parameters, etc? This seems counter-intuitive so I just want to double check. This also appears to be interfering with existing PHPCS rules (see phab:T398711). Thanks. –Novem Linguae (talk) 12:31, 5 July 2025 (UTC)

I believe you’re never supposed to. If Title is split up, type declarations will cause runtime errors everywhere they’re used, including class properties, parameters, and return types. —Tacsipacsi (talk) 22:44, 5 July 2025 (UTC)

Translation

@Jdforrester (WMF): I have my disagreements with @Shirayuki every now and then but in this case I don't think he did anything wrong other than fiddling with tabs/spaces and removing some commas, which I agree he shouldn't have. However, translating inlined comments is to be expected since this is a translatable page, otherwise what's the point? This is no "drive-by" editing, he's just doing his job. Tactica (talk) 19:39, 23 July 2025 (UTC)

@Tactica: In this edit and then this edit, @Shirayuki reverted edits made by a long-standing developer, claiming he was doing it to "restore translation units :(", with (a) the implicit assumption that the person who made the edits didn't know what they were doing, and (b) the effect of edit-warring to restore their own edits. This is passive-aggressive, and not OK by the rules of pretty much any wiki. I would expect this kind of revert to ideally be first a talk page thread first, and always a talk page thread afterwards to justify and seek consensus.

translating inlined comments is to be expected since this is a translatable page

No? Inline comments in specimen code files are absolutely not meant to be translated; if someone copy-pastes the content, they should not end up with <tvar> etc. wikitext line noise interfering. The section is labelled "Exemplified safe configuration".

otherwise what's the point

There is marginal, but real, value in translating developer-focused pages, to help them understand the context. There is negative value in inserting translatable content into code files going into repos, like PHP, JS, CSS, etc., and we should continue to be vigilant and ensure we don't break the value of these by adding such mal-adapted content. Jdforrester (WMF) (talk) 19:48, 23 July 2025 (UTC)
OK, I see what you mean and I should have checked further back in the history before voicing an opinion. Though maybe your assessment of what should be translated and what not should go somewhere in the manual for language/translation admins if it isn't there already. I know I'd probably have made the same mistake. Tactica (talk) 19:59, 23 July 2025 (UTC)
@Jdforrester (WMF): I was not the one who originally made the code comments translatable, so the phrase "restore their own edits" does not apply here.
The removed translation units had already been translated into multiple languages by various translators (again, not me), so I believe they deserve a certain level of respect as well: -- Shirayuki (talk) 21:28, 23 July 2025 (UTC)
@Shirayuki: I'm sorry, you are right. We should all be careful to ensure that we do not set up lures for translators to spend their time where it's not valuable! Jdforrester (WMF) (talk) 23:02, 24 July 2025 (UTC)