Re: Tutorial and guidelines: A proposal for better OpenSource code (long message)

From: Nick Landsberg (hukolau_at_NOSPAM.att.net)
Date: 05/30/04 

Date: Sun, 30 May 2004 20:00:36 GMT

Otto Wyss wrote:
> Since too much OpenSource code does _not_ keep up with my expectation
> I've created some guidelines which should help improve it. These
> guidelines have always sample code associated so they could be used as a
> simple tutorial. Everyone is free to choose if any guideline makes sense
> and is applied to his projects.
>
> To get the most out of these guidelines each should be well acceptable
> by a large community of OpenSource coders. Currently they more or less
> only represent my personal experience and mostly what I think is
> important is included. To change that, to make each guideline acceptable
> by a broader audience and to fill in the gaps, I'm planning to send each
> guideline on a weekly (or biweekly) basis to this newsgroup. Since this
> probably will produce rather much traffic I leave it up to the readers
> of this group if they like it or if I should stop it.
>
> The best would be if you allow me to just go ahead and simply stop
> answering if you think it's not worth. Then if I don't get at least
> answers like "This guidelines is useless/acceptable/perfect" or
> anything, I'll stop sending more guidelines. Also even if I send the
> guidelines to all interested newsgroups I won't cross post except CC to
> wxguide-users mailing list. So if you are interested in what other
> newsgroup think about the guidelines you have to be subscribed there or
> to wxguide-users. When you answer please CC
> "wxguide-users@lists.sourceforge.net" so there will be a complete
> archive.

After some thought, it looks like a language-specific newsgroup is
inappropriate, so that this newsgroup is as good as any.

>
> To give you an idea how these messages look like I'll add the first
> guideline to discuss below. Each guideline will sooner or later be
> discussed in a separate message. Please only answer to a guideline
> within the timeframe (weekly or biweekly) if you have to remark
> something to a guideline later on or any other remarks, do it to
> wxguide-users.
>
> =================================================================
> Tutorial and guidelines: Coding standards, Naming
>
> # Do only discuss this guideline, for any other remark change the
> # subject send it only to wxguide-users mailing list. Do not
> # answer after the next message is sent or only to wxguide-users.
> # If you think it's just "bull***" or simply "not worth" just
> # stop answering. I'll stop if I don't see any interests.
> #
> # Please shorten your answer and quote as less as possible. I know
> # what I've written or can look in the archive.
>
> Coding standards, Naming
> ========================
>
> Rules for choosing good names are rather difficult to specify. But
> naming is nonetheless not an obscure art as some may think, it's just
> difficult since names always have a context around them which influences
> their naming.
>
> The usual rule about size of a name should not be followed too strictly.
> It's much better to make important (global) names longer, less important
> (local) names shorter. So it's perfectly correct to use "i" for a loop
> variable while it's completely nonsense to call an important function
> "i". Or don't call a loop variable "loopIndexOfFunctionXY" while it
> makes sense to call it "pos" if it refers to a position.
>
> A name should usually just mean what it does or what it stands for. So a
> name of a function should specify what a function does, even if this
> means a longer name. So function names are usually action descriptions
> while variable names are usually object descriptions.
>
> In class oriented languages (C++) it's a good idea to make the scope
> visible. Global objects should have a "g_" prepended, class objects
> (members) a "m_" while local object may not have a prefix. Other
> languages might distinct between global ("g_") and local (no prefix)
> objects. If you make the scope visible you have to be consequent and do
> it throughout the full project.
>
> It's not a good idea to prepend (nor append) the type of an object to
> its name. There aren't enough symbols to be consequent and they conflict
> with the scope, making them useless. Appending a type makes only sense
> if it's needed to distinguish between the equally named variable and the
> type.

I think you will get some disagreement on this point. It is
common for types in c to have "_t" appended, e.g. "size_t"
indicates a "size type", similarly for "time_t", etc.
If that isn't what you meant, sorry.
Often the prepending of the type is useful for code
maintenance purposes. For example,

struct foo *p_foo;

(or the equivalent typedef)

gives an indication to the *maintainer* of the code
that p_foo is a pointer, rather than the struct
itself. YMMV.

By the way, I presume you meant "consistent" rather than
"consequent" in the above paragragh.

>
> If you can avoid it don't use letter case to distinguish between
> objects. Do it only between objects and their types and even then avoid
> it. Use case to make names better readable but always use identical
> writing even not enforced by the language or compiler. If you prefer use
> underscores to improve readability.

This one I will endorse wholeheartedly! Several years ago
on a project, we had a poorly performing method and a
decently performing method where the names
were only distinct because of the case of one of
the letters in the name. They did the same thing,
but one was linear with size of input, while the other
was exponential. The simple solution would have been
to expunge the exponential one and re-define it to
be either a #define or an in-line method which
called the linear one, but, for some reason, that
wasn't what was done... Stupidity is its own reward,
sigh.

Developer: "But I'm calling "Transmogrify_String()"
Management: "You should be calling "TransMogrify_String()"

>
> See: "http://wxguide.sourceforge.net/guidelines/coding.html#naming"
>
> O. Wyss
> 

-- 
"It is impossible to make anything foolproof
because fools are so ingenious"
  - A. Bloch
Quantcast