Rant time! (Wait. That's every time... Well, this time I'm actually typing it into my blog.) This is all about computer programming so if you don't know anything about computer programming you are officially off the hook! (Enjoy your day!)
Coding style guidelines are usually a matter of opinion. But here's one of my opinions, and in my opinion, it's not an opinion, it's a fact.
Apart from normal start-of-line indent, trying to align lines of code horizontally is always wrong.
Here are three examples. For each one I'll give WRONG then RIGHT.
WRONG:
$this->something = $something;
$this->x = $x;
Right:
$this->something = $something;
$this->x = $x;
WRONG:
$thing = array(
'value' => 1,
'anothervalue' => 2,
'more' => 3);
Right:
$thing = array(
'value' => 1,
'anothervalue' => 2,
'more' => 3);
WRONG:
$something->function1()->function2($variable, $anothervariable,
$yetanothervariable) {
Right:
$something->function1()->function2($variable, $anothervariable,
$yetanothervariable) {
etc.
The wrong examples are wrong because computer code is not carved in stone, nor even printed on paper. (When you're grave-carving or desktop-publishing, feel free to make things line up. When you're computer-programming, stop it! Now!) Unlike gravestones and newsprint, computer code changes.
Let's say I add a variable called $slightlylonger to the list of assignments. With the right code, this involves me adding one code line. With the wrong code, I have to add one code line, but now I have to modify 2 other code lines as well to make the stupid thing consistent.
Similarly if I change the name of one of the functions I would now have to go around changing all the following lines as well, where it wrapped to multiple lines. (The function example is also bad because horizontal space is usually at a premium, which is why you're having to wrap lines in the first place; when you wrap the line, you want to get a useful amount of increased space for adding more parameters in future. That doesn't happen if the wrap point is artificially shifted to way up near the end.)
Having to modify extra lines matters for two reasons: first, making the changes is annoying, and second, the more lines you touch then the more chance of a conflict in your version control system.
In addition, as I'm sure the newspaper designer would tell you, both these approaches are bad even from a layout and visual design perspective. They result in 'columns' that start every which way at random points. It's messy.
So, much better not to make it line up in the first place. If you disagree... well there's a word in bold in this post... let's leave it there
Rant over!
And no this wasn't directed at any particular developer, or even the Moodle project. Just, grr.
I'll try to write a blog post about something more specific to do with our Moodle developments next time. But this is better than nothing, right?