Quite a nice read on the coding style used in Doom.

http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550

On 01/14/2013 11:24 AM, Walter Bright wrote:
> Quite a nice read on the coding style used in Doom.
>
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
>

Here begins another epic thread. :)

I haven't read the article but came across this: "I personally enforce the rule that all method names should begin with a verb unless they can't." The author adds that he prefers getLength() to length().

That rule is misguided because not every member function represents an action; there are also attributes. Attribute methods should be nouns, in D or in C++. In our C++ code we simply say length() (and setLength() if needed).

Ali

On 1/14/2013 11:52 AM, Ali Çehreli wrote:
> On 01/14/2013 11:24 AM, Walter Bright wrote:
>> Quite a nice read on the coding style used in Doom.
>>
>> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
>>
>>
>
> Here begins another epic thread. :)
>
> I haven't read the article but came across this: "I personally enforce the rule
> that all method names should begin with a verb unless they can't." The author
> adds that he prefers getLength() to length().
>
> That rule is misguided because not every member function represents an action;
> there are also attributes. Attribute methods should be nouns, in D or in C++. In
> our C++ code we simply say length() (and setLength() if needed).

Well, not everyone will agree with everything he says. But it is interesting, and a number of the conventions in there are D features.

I also found it interesting how some of the conventions used defies generally accepted C++ best practices.

On Monday, 14 January 2013 at 20:36:51 UTC, Walter Bright wrote:
> On 1/14/2013 11:52 AM, Ali Çehreli wrote:
>> On 01/14/2013 11:24 AM, Walter Bright wrote:
>>> Quite a nice read on the coding style used in Doom.
>>>
>>> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
>>>
>>>
>>
>> Here begins another epic thread. :)
>>
>> I haven't read the article but came across this: "I personally enforce the rule
>> that all method names should begin with a verb unless they can't." The author
>> adds that he prefers getLength() to length().
>>
>> That rule is misguided because not every member function represents an action;
>> there are also attributes. Attribute methods should be nouns, in D or in C++. In
>> our C++ code we simply say length() (and setLength() if needed).
>
> Well, not everyone will agree with everything he says. But it is interesting, and a number of the conventions in there are D features.
>
> I also found it interesting how some of the conventions used defies generally accepted C++ best practices.

Apart from a few *style* issues, the only thing the article contains was mostly hate for the stl.

I understand one might dislikes the stream operators due to the syntax (myself included), but once you've used them more than once, and know how to use them, they aren't a problem. The strong typing they provide is simply unmatched in C++. The article even mentions that NOT using stream operators was one of their biggest source of bugs. And Carmack himself replies stating that in retrospect: StrongTyping > WeirdCode.

There's also hate for stl's containers, stating they are *too generic*, stating that it is better to use *Only* a HashTable of <int, int> or <char*, int>. Nobody is stopping you from doing it with the stl. Not being overly generic is one thing. Not using something specific because it *spawned* from something generic is another.

The argument is *always* the same "the syntax is ugly and hard to use and outside of my comfort zone".

On Monday, 14 January 2013 at 19:24:25 UTC, Walter Bright wrote:
> Quite a nice read on the coding style used in Doom.
>
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550

That guy has rather weird sense of beauty... My eyes started bleeding at the "Spacing" section.

On Mon, Jan 14, 2013 at 09:57:25PM +0100, monarch_dodra wrote: [...]
> >>On 01/14/2013 11:24 AM, Walter Bright wrote:
> >>>Quite a nice read on the coding style used in Doom.
> >>>
> >>>http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
[...]
> Apart from a few *style* issues, the only thing the article contains was mostly hate for the stl.
> 
> I understand one might dislikes the stream operators due to the syntax (myself included), but once you've used them more than once, and know how to use them, they aren't a problem. The strong typing they provide is simply unmatched in C++. The article even mentions that NOT using stream operators was one of their biggest source of bugs. And Carmack himself replies stating that in retrospect: StrongTyping > WeirdCode.

Stream operators are teh eviil. Overloading << and >> for I/O was a
horrible design decision. Operator overloading should be reserved for
numeric types. But then again, Stroustrup didn't have the benefit of
hindsight back then, and certainly, on the surface, overloading <<
and >> seemed like a cool thing to do. And C++ didn't (still doesn't?)
have typesafe handling of variadics, so the desire to not have to write
"cout.put(x); cout.put(y); cout.put(z); cout.put(w); ..." is
understandable.

But none of that changes the fact that overloading << and >> for I/O was a horrible idea.


> There's also hate for stl's containers, stating they are *too generic*, stating that it is better to use *Only* a HashTable of <int, int> or <char*, int>. Nobody is stopping you from doing it with the stl. Not being overly generic is one thing. Not using something specific because it *spawned* from something generic is another.

I don't think it's so much as a complaint about genericity, as the lousy C++ template syntax.


> The argument is *always* the same "the syntax is ugly and hard to use and outside of my comfort zone".

Which is why D's template syntax is such a big plus.

The prevalent hatred for templates is mostly the fault of poorly-chosen syntax on C++'s part. Overloading < and > to delimit template arguments was just such a horribly bad idea. It makes C++ impossible to lex before it's parsed, and gives templates an undeservedly frightening appearance. Unfortunately, the best of us coders are prone to judge by appearances, especially when dealing with an unfamiliar new language feature (which was the case when C++ templates first appeared on the scene). Sometimes, syntax matters.

I think people learning about templates for the first time in D syntax would be much less liable to developing an aversion to it. In fact, TDPL was written in such a way that the word 'template' isn't even used until the reader has already gotten used to the concept of "compile-time parameters". When understood in this way, templates are far more approachable than is the case in most introductions to C++ templates.

D templates can still stand some improvement, though. Maybe not so much at the language level, but template-related errors in DMD are still a frightening sight to behold for the uninitiated. Phobos also can stand a lot of improvement in providing human-readable errors in a catch-all default template, so that a failed instantiation doesn't produce 27 pages of errors, most of which involve details of internal Phobos implementation structures that no outside user should need to know about.  Improvement this area will help a lot towards newbie acceptance of the concept of templates.


T

-- 
One disk to rule them all, One disk to find them. One disk to bring them all and in the darkness grind them. In the Land of Redmond where the shadows lie. -- The Silicon Valley Tarot

On Monday, 14 January 2013 at 19:24:25 UTC, Walter Bright wrote:
> Quite a nice read on the coding style used in Doom.
>
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550

I think more important than any aspect of a particular coding style is that style guidelines ensure that code is written in a consistent manner. The advantage is that, even if it's a "bad" style, you can learn to read and write code in that style which makes things predictable. You learn conventions which tell you how to use classes and functions without the need to refer to documentation. When convention isn't enough, you learn where to find the information you need (can it be inferred from the code? is it clearly stated in a comment or documentation?). If nothing else, you simply learn to read and interpret code written in a certain style.

It's certainly to the benefit of developers to have a good coding style. But the only thing worse than a bad coding style is a mix of styles which makes code inconsistent and unpredictable. There needs to be a consensus among the developers on a style guideline.

On 1/14/2013 11:24 AM, Walter Bright wrote:
> Quite a nice read on the coding style used in Doom.
>
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
>

Looks like it made reddit:

http://www.reddit.com/r/programming/comments/16k7hm/the_exceptional_beauty_of_doom_3s_source_code/

On 2013-01-14 22:31, mist wrote:
> That guy has rather weird sense of beauty... My eyes started bleeding at the
> "Spacing" section.


I sympathize. He posted the worse code excerpt to prove his point. :)

I used to also do "column alignment" in the C code I wrote in the past, but using spaces and not tabs. Used it for initializing arrays of structs, for defining a series of bit masks (I bet you have nothing against this use), but also for a series of function pointer typedefs, for comments and sometimes for cases in a switch statement.

I think it adds readability when you compare similar lines and you don't even need syntax highlighting -- as long as the columns are kept narrow (but wide enough, so that you don't have to push all things whenever you add a line).

The columns idea is mentioned in the file CodeStyleConventions.doc used by idSoftware, which he links on that page. Here are some of the conventions:


> Use real tabs that equal 4 spaces.
Huh? No tabs, ever!. They usually mess up code posted on webpages.

> Pad parenthesized expressions with spaces:
> if ( x ) {}  Instead of  if (x) {}  And
> x = ( y * 0.5f );  Instead of  x = (y * 0.5f);
I agree that it's readable, even more so with functions:
someFunction( parameter1, parameter2 ).method( something );

> Function names start with an upper case:
> void Function( void );
Say what?!

> Typedef names use the same naming convention as variables,
> however they always end with "_t".
> typedef int fileHandle_t;
Now, this is completely reversed...

> Use ‘const’ as much as possible.
Yes, generally good.


> Indent the names of class variables and class methods to make nice columns.
> The variable type or method return type is in the first column and the
> variable name or method name is in the second column.
>
> class idVec3 {
>     float           x;
>     float           y;
>     float           z;
>     float           Length( void ) const;
>     const float *   ToFloatPtr( void ) const;
> }
>
> The * of the pointer is in the first column because it improves readability
> when considered part of the type.

Generally yes, but I can't agree with * being with the type, unless there's always just one variable per line or we're writing in D, for example.

On 01/14/2013 08:24 PM, Walter Bright wrote:
> Quite a nice read on the coding style used in Doom.
>
> http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code?post=56177550
>

It is funny how statements about beauty of code tend to overemphasize the importance of trivial formatting rules. This is completely irrational. Formatting is a part of the process that could be trivially automated. It is not what the substance is.