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
_______________________________________________
phobos mailing list
[email protected]
http://lists.puremagic.com/mailman/listinfo/phobos
