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

From: Otto Wyss (otto.wyss_at_orpatec.ch)
Date: 05/30/04

  • Next message: Edd: "Creation of static libs with MS VC++ Toolkit 2003" 
    Date: Sun, 30 May 2004 20:07:35 +0200

    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.

    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.

    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.

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

    O. Wyss 

    -- 
See wyoEditor at "http://freshmeat.net/projects/wyoeditor/"
  • Next message: Edd: "Creation of static libs with MS VC++ Toolkit 2003"