[phobos] Initial Phobos style guide proposal

[spir]

On 03/31/2011 05:00 AM, Jonathan M Davis wrote:
> General Coding Guidelines
> -------------------------
> - Prefer anonymous temporaries to named values within reason.

Is this really wished? It's often helpful to readability (provided the name is 
clear).
It also helps making shorter lines without sacrificing any other good point (eg 
by giving a temp name to a complicated function argument expression).

> - Avoid having 2+ empty lines in a row and reasonably minimize how many empty
>    lines are within a function.

Unlike you, I like this. Rather than empty lines, I often have short comments 
giving kind of titles to sections of a function. I insert a blank line when 
there are already useful line-level comments.
(see also below)

> - Try to fit functions loosely on one editor page.
>

> - Avoid meaningless aliases. Use aliases when reasonable, but we don't want
>    to pollute the namespace with unnecessary aliases.

To be complete: Use aliases when they provide conceptual information, or 
otherwise clarify the code:
     alias float[3] Position;
     alias Node* Link;
     alias double Time;
     alias ElementType!T Element;

Also: couldn't this go to the Naming Conventions section?

> - Do not use Hungarian notation.

Shouldn't this go to the Naming Conventions section?

=== points below: I would add a Doc & Comment section
> - All public declarations should have proper ddoc documentation.
>
> - If you need to use a version block for documentation, use version(StdDoc),
>    not version(D_Ddoc).
>
> - DDoc documentation should be generatable for all OSes, so if you have
>    multiple versions of a function for differing OSes or if a function doesn't
>    exist on all OSes, then either put the version blocks within the function
>    or use a version(StdDoc) with a declaration of the function (without a body)
>    and the documentation.
>
> - Comments should be high level (describing 3-10 lines) instead of low-level
>    (describing the mechanics of the next line, which are already obvious in
>    code).

I would tell apart meaningful comments:
"
Comments that describe what the code mechanically does usually are useless this 
is already obvious in code. Instead provide comments when the code's actual 
/meaning/ is not obvious:
     // Case node is a leaf:
     if (node.kind == 0)
vs
     if (node.kind == NodeKind.leaf)
"


-- 
_________________
vita es estrany
spir.wikidot.com