D/Phobos Style guide

Question

I've just begun looking at the phobos source, and it's littered with several different styles and commented out code.

The style guide on the web side is very small, and I only found broken links from 2006 and another one from 2004...

Is there a newer, more comprehensive guide available?

PS: Originally asked at the D.learn newsgroup, but as I didn't get any answers, I thought I might try here even though it might be a shot in the dark

Monicamonie

Answer 1

Whatever guide exists is out of date and shouldn't exist anymore. I don't believe that there is any sort of D style guide which is considered valid, and I don't think that Walter Bright, Andrei Alexandrescu, etc. want there to be one. Also, as I recall, in C++ Coding Standards: 101 Rules, Guidelines, and Best Practices, Herb Sutter and Andrei said that style guides were a bad idea (or at least that really specific ones were), but I'd have to pull out the book to be sure of exactly what they said. So I rather doubt that Phobos (which Andrei is in charge of) would have any kind of style guide; I'm certainly not aware of any. There may be some sort of guidelines for formatting code that goes into Phobos (like making your code look similar to the rest of the module or somesuch), but someone like Andrei or one of the other Phobos developers would have to answer that. Certainly, with about 15 different developers working on Phobos, you're bound to get several different styles in the code if there is no enforced style guide.

So, I don't believe that there really is any kind of recommended coding style for either D or Phobos. As I understand it, the main folks behind D aren't particularly in favor of style guides, and they certainly haven't pushed one. So, there isn't really one right now, and I don't expect there to be one in the future.

EDIT: Okay, I went and looked up exactly what Herb Sutter and Anderi Alexandrescu said in C++ Coding Standards: 101 Rules, Guidelines, and Best Practices. It's not exactly that they're against coding standards so much as they're against particularly restrictive ones which enforce personal tastes or obsolete practices. I'm not going to quote the whole thing here (it's a good book, and you should probably pick it up anyway), but here are some key points.

• Don't specify how much to indent, but do indent to show structure.
• Don't enforce a specific line length, but do keep line lengths readable.
• Don't overlegislate naming, but do us a consistent naming convention.
• Don't precsribe commenting styles (except where tools extract certain styles into documentation), but do write useful comments.

Some examples that they gave were that

• Brace placement shouldn't matter but it should be consistent and readable.
• On spaces vs tabs, they don't seem to care whether the coding standard says anything about it.
• They're against Hungarian notation in C++ but think that it might be valuable in less type-safe languages.
• They're completely against enforcing that there be a single return statement in a function.

Regardless, they do think that formatting should be consistent within a source file. Obviously Phobos doesn't necessarily stick to that at this point, but Andrei did just bring up on the newsgroup some of the conventions that have typically held to and was looking at possibly enforcing some of them (the actual post is archived here).

However, while Phobos is open source and anyone is free to submit patches, remember that it's the API that's meant for public consumption. Only the Phobos developers need to look at the code (at least if the docs are appropriately complete) - certainly they're the only ones who are going to be working on it directly - so there's no need for a publicly listed coding standard, even if they use one. It does look like they could use more consistency and that they may be working on that, but all that's going to do for 3rd parties is make it more readable. No one else really needs to know what the standard actually is (though if you looked at enough code following a standard, you could figure out at least more or less what the standard said).

As for D at large, there are certain conventions which are considered good practice (such as generally using auto instead of specifying a type, unless you actually have to specify the type), but just as with C++, you can code with whatever coding style you want, and the D devs aren't dictatorial enough to try enforce a style on the whole D community.

Pugliese

Too bad. I find it easier to read code when it's consistent. D does exactly the opposite of Go here :| – Monicamonie

I agree. Phobos is in desperate need of a style guide. Every time you look at a different part of the library the style changes -- even the naming conventions. It makes Phobos very difficult to use. – Skell

@Peter: I guess it will eventually happen out of desperate need. It's even worse on modules written by several people - they don't even try to stick with the style previously used. – Monicamonie

I wouldn't count on it. Just look at PHP's libraries; they are also horribly inconsistent with their naming and other conventions, and nothing has been done about them. Once a language is in wide use, names have to stay the same for backwards compatibility. D2 is still young enough to make changes, so it has to happen now. – Skell

This is why we need dfmt, a D version of gofmt. It shall have //@NOFORMAT macros in the doc to prevent formatting of a code section if for whatever reason the user wants to override formatting. – Jointer

@Jointer I think dfmt existed since quite a while ago ;-) – Dalrymple

Answer 2

Things have changed enough that I think that I should re-answer this question. You can see the current D style guide here, and it's now up-to-date. It has a few rules about formatting (e.g. no tabs and each level of indentation is 4 spaces), but almost all of the rules are about naming conventions (e.g. type names are supposed to use PascalCase, whereas variables and functions are supposed to use camelCase). So, the focus is on what the API should look like and not how the code should be formatted. And as I detailed in my previous answer, it will never be the case that the Phobos devs try and mandate an official formatting style for D as a whole. As it is, there are plenty of D programmers who don't even follow the naming conventions in the official style guide.

It's possible that more restrictive formatting guidelines will be put into place on Phobos itself in the future (it has been discussed but never done) in order to make it clearer to submitters what style they should follow and avoid arguments over code formatting (that's become more of an issue since we moved to github and the number of submitters has increased considerably), but at this point, it primarily just comes down to making sure that the code within a module is formatted consistently. But again, even if more restrictive formatting rules were mandated for Phobos, that would be specific to Phobos and not be for the D community as a whole. And there are far too many different opinions on how code should be formatted for a community wide formatting standard to ever work.

Pugliese