Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

D/Phobos Style guide

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

like image 295
simendsjo Avatar asked Aug 13 '10 20:08

simendsjo


1 Answers

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.

like image 71
Jonathan M Davis Avatar answered Oct 07 '22 05:10

Jonathan M Davis