View mode: basic / threaded / horizontal-split · Log in · Help
January 14, 2013
Exceptional coding style
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
January 14, 2013
Re: Exceptional coding style
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
January 14, 2013
Re: Exceptional coding style
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.
January 14, 2013
Re: Exceptional coding style
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".
January 14, 2013
Re: Exceptional coding style
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.
January 14, 2013
Re: Exceptional coding style
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
January 14, 2013
Re: Exceptional coding style
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.
January 14, 2013
Re: Exceptional coding style
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/
January 14, 2013
Re: Exceptional coding style
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.
January 14, 2013
Re: Exceptional coding style
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.
« First   ‹ Prev
1 2 3 4 5
Top | Discussion index | About this forum | D home