Comment Banner/Header best practices/examples?

Question

Long ago, I got a quick glance at some code (PERL... urp) one of my managers was writing and was stunned by the banner/heading system he used in his code. I didn't get a chance to delve into his code in detail, but just from the banner comments on the screen I could easily tell what the code was meant to do, even from far away.

Unfortunately that was long ago and our conversation at the time did not lend itself to me saying, "Yeah, well forget about our dot-com startup going down the toilet, can I take notes on your coding style?"

Years later, I've not yet achieved a high-level comment style that has the clarity as the (probably now mythical) code I saw that day.

When I say, "banners", I'm referring to the high-level block divisions/headers many coders use to create higher-level devisions in their code. They're usually made up of simple ASCII dashes, slashes, equal signs, etc. In my current daily-use language, one code banner/header hierarchy might be:

# ========================================================
# = Header 1
# ========================================================

# --------------------------------------------------------
# - Header 2
#---------------------------------------------------------

# == Header 3 ============================================

# -- Header 4 --------------------------------------------

# Header 5

and all the usual variations.

Although my searches have turned up nothing noteworthy, surely somewhere on the web someone's attempted to collect examples of these and present them in a systematic manner?

Can someone point to banner comment style "systems" they've found useful? I'm not thinking of "Oh, I like the ones using asterisks", but more of an overall strategy of styles that makes high-level code construction quick and easy to understand as well as easy on the eyes? Picking a preferred system from examples would be easier than comparing descriptions, obviously.

Note: I'm not interested in the contents of the comments per se, but the "flair" used on the comments to provide a clear indications of overall code content and organization.

Answer 1

One of the best ways I have found of verifying the style of commenting is to use a code documentation tool such as doxygen, there is a list of others here, and then see what the output was like - the clearer the output the better the comments.

I would say that the single biggest points are consistency and a clear indication of ranking, followed by completeness and conciseness, i.e. Once you have looked at one you should know what the others will look like and how significant the one you are looking at is. This forces you to have a good design as without it you don't know how significant things are.

Next all the information you need should be present but it should be short enough to take in at a glance - however satisfying both these forces you to change your coding style so that objects/code is not too large, is well named, doesn't have too many parameters, etc., all the things that tools like lint try to teach us.

For python code the style summary at PEP-257 provides a lot of useful guidelines and some examples.

A quick look for some "Good" code on my machine turned up Andrea Gavana's Aquabutton.py I have included a section of the code below but you can see the full code here - I have to say that this was the first module of Andrea's that I opened, being early in the alphabet but I am sure any would have done.

# --------------------------------------------------------------------------------- #
# AQUABUTTON wxPython IMPLEMENTATION
#
# Andrea Gavana, @ 07 October 2008
# Latest Revision: 24 Nov 2011, 22.00 GMT
#
#
# TODO List
#
# 1) Anything to do?
#
#
# For all kind of problems, requests of enhancements and bug reports, please
# write to me at:
#
# [email protected]
# [email protected]
#
# Or, obviously, to the wxPython mailing list!!!
#
#
# End Of Comments
# --------------------------------------------------------------------------------- #

"""
:class:`AquaButton` is another custom-drawn button class which *approximatively* mimics
the behaviour of Aqua buttons on the Mac.


Description
===========

:class:`AquaButton` is another custom-drawn button class which *approximatively* mimics
the behaviour of Aqua buttons on the Mac. At the moment this class supports:

* Bubble and shadow effects;
* Customizable background, foreground and hover colours;
* Rounded-corners buttons;
* Text-only or image+text buttons;
* Pulse effect on gaining focus.

And a lot more. Check the demo for an almost complete review of the functionalities.


Usage
=====

Sample usage::

    import wx
    import wx.lib.agw.aquabutton as AB

    app = wx.App(0)

    frame = wx.Frame(None, -1, "AquaButton Test")

    mainPanel = wx.Panel(frame)
    mainPanel.SetBackgroundColour(wx.WHITE)

    # Initialize AquaButton 1 (with image)
    bitmap = wx.Bitmap("my_button_bitmap.png", wx.BITMAP_TYPE_PNG)
    btn1 = AB.AquaButton(mainPanel, -1, bitmap, "AquaButton")

    # Initialize AquaButton 2 (no image)
    btn2 = AB.AquaButton(mainPanel, -1, None, "Hello World!")

    frame.Show()

    app.MainLoop()


Supported Platforms
===================

AquaButton has been tested on the following platforms:
  * Windows (Windows XP);
  * Linux Ubuntu (10.10).


Window Styles
=============

`No particular window styles are available for this class.`


Events Processing
=================

This class processes the following events:

================= ==================================================
Event Name        Description
================= ==================================================
``wx.EVT_BUTTON`` Process a `wxEVT_COMMAND_BUTTON_CLICKED` event, when the button is clicked.
================= ==================================================


License And Version
===================

:class:`AquaButton` control is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 22 Nov 2011, 22.00 GMT

Version 0.4

"""

import wx

# Constants for the hovering and clicking effects
HOVER = 1
""" Indicates that the mouse is hovering over :class:`AquaButton` """
CLICK = 2
""" Indicates that :class:`AquaButton` has been clicked """


class AquaButtonEvent(wx.PyCommandEvent):
    """ Event sent from the :class:`AquaButton` buttons when the button is activated. """

    def __init__(self, eventType, eventId):
        """
        Default class constructor.

        :param integer `eventType`: the event type;
        :param integer `eventId`: the event identifier.
        """

        wx.PyCommandEvent.__init__(self, eventType, eventId)
        self.isDown = False
        self.theButton = None


    def SetButtonObj(self, btn):
        """
        Sets the event object for the event.

        :param `btn`: the button object, an instance of :class:`AquaButton`.
        """

        self.theButton = btn

snip

class AquaButton(wx.PyControl):
    """ This is the main class implementation of :class:`AquaButton`. """

    def __init__(self, parent, id=wx.ID_ANY, bitmap=None, label="", pos=wx.DefaultPosition,
                 size=wx.DefaultSize, style=wx.NO_BORDER, validator=wx.DefaultValidator,
                 name="aquabutton"):
        """
        Default class constructor.

        :param Window `parent`: parent window. Must not be ``None``;
        :param integer `id`: window identifier. A value of -1 indicates a default value;
        :param Bitmap `bitmap`: the button bitmap (if any);
        :param string `label`: the button text label;
        :param `pos`: the control position. A value of (-1, -1) indicates a default position,
         chosen by either the windowing system or wxPython, depending on platform;
        :type `pos`: tuple or :class:`Point`
        :param `size`: the control size. A value of (-1, -1) indicates a default size,
         chosen by either the windowing system or wxPython, depending on platform;
        :type `size`: tuple or :class:`Size`
        :param integer `style`: the button style (unused);
        :param Validator `validator`: the validator associated to the button;
        :param string `name`: the button name.
        """

        wx.PyControl.__init__(self, parent, id, pos, size, style, validator, name)

        self.SetBackgroundStyle(wx.BG_STYLE_CUSTOM)

        self.Bind(wx.EVT_PAINT, self.OnPaint)
        self.Bind(wx.EVT_ERASE_BACKGROUND, lambda event: None)
        self.Bind(wx.EVT_SIZE, self.OnSize)
        self.Bind(wx.EVT_LEFT_DOWN, self.OnLeftDown)
        self.Bind(wx.EVT_LEFT_UP, self.OnLeftUp)
        self.Bind(wx.EVT_LEAVE_WINDOW, self.OnMouseLeave)
        self.Bind(wx.EVT_ENTER_WINDOW, self.OnMouseEnter)
        self.Bind(wx.EVT_SET_FOCUS, self.OnGainFocus)
        self.Bind(wx.EVT_KILL_FOCUS, self.OnLoseFocus)
        self.Bind(wx.EVT_KEY_DOWN, self.OnKeyDown)
        self.Bind(wx.EVT_KEY_UP, self.OnKeyUp)
        self.Bind(wx.EVT_TIMER, self.OnPulseTimer)

        if "__WXMSW__" in wx.PlatformInfo:
            self.Bind(wx.EVT_LEFT_DCLICK, self.OnLeftDown)

        self._mouseAction = None
        self.SetBitmapLabel(bitmap)
        self._hasFocus = False
        self._saveBitmap = True
        self._storedBitmap = wx.NullBitmap
        self._pulseOnFocus = False
        self._gammaFactor = 1.0
        self._gammaIncrement = 0.1

        self._timer = wx.Timer(self, wx.ID_ANY)

        self.SetLabel(label)
        self.InheritAttributes()
        self.SetInitialSize(size)

        # The following defaults are better suited to draw the text outline
        if "__WXMAC__" in wx.PlatformInfo:
            self._backColour = wx.Colour(147, 202, 255)
            self._hoverColour = self.LightColour(self._backColour, 30)
            self._disableColour = self.LightColour(self._backColour, 70)
            self._textColour = wx.BLACK
        else:
            self._backColour = wx.SystemSettings.GetColour(wx.SYS_COLOUR_ACTIVECAPTION)
            self._hoverColour = self.LightColour(self._backColour, 30)
            self._disableColour = self.LightColour(self._backColour, 70)
            self._textColour = wx.WHITE


    def SetBitmapLabel(self, bitmap):
        """
        Sets the bitmap label for the button.

        :param `bitmap`: the bitmap label to set, an instance of :class:`Bitmap`.
        """

        self._bitmap = bitmap
        self.Refresh()