coding-style - 评论横幅/标题最佳实践/示例？

Question

很久以前，我快速浏览了我的一位经理正在编写的一些代码(PERL...urp)，并被他在代码中使用的横幅/标题系统惊呆了。我没有机会详细研究他的代码，但仅从屏幕上的横幅注释我就可以很容易地知道代码的用途，即使是在很远的地方。

不幸的是，那是很久以前的事了，当时我们的谈话并没有让我说，“是的，好吧，忘记我们的互联网创业公司正在下厕所，我可以记录一下你的编码风格吗？”

多年后，我还没有达到我那天看到的(可能现在是神话般的)代码那样清晰的高级注释风格。

当我说“横幅”时，我指的是许多编码人员用来在其代码中创建更高级别的划分的高级 block 划分/标题。它们通常由简单的 ASCII 破折号、斜杠、等号等组成。在我目前的日常使用语言中，一个代码横幅/标题层次结构可能是:

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

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

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

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

# Header 5

以及所有常见的变化。

尽管我的搜索结果没有任何值得注意的地方，但肯定有人试图在网络上的某个地方收集这些示例并以系统的方式呈现它们？

有人可以指出他们发现有用的横幅评论风格“系统”吗？我不是在想“哦，我喜欢那些使用星号的”，而是更多的整体风格策略，使高级代码构建快速、易于理解并且易于阅读？显然，从示例中选择首选系统比比较描述更容易。

注意:我对评论本身的内容不感兴趣，但评论中使用的“天赋”可以清楚地表明整体代码内容和组织。

Answer 1

我发现验证注释风格的最佳方法之一是使用代码文档工具，例如 doxygen，还有其他列表 here ，然后看看输出是什么样的——输出越清晰，评论就越好。

我想说，最大的一点是一致性和排名的明确指示，其次是完整性和简洁性，即一旦你看过一个，你应该知道其他的会是什么样子，以及你正在看的那个有多重要。这迫使你有一个好的设计，因为没有它你不知道事情有多重要。

接下来应该提供您需要的所有信息但是 它应该足够短，一目了然——无论多么令人满意两个这些迫使你改变你的编码风格 这样对象/代码不会太大，命名良好，没有太多参数等，所有这些都是像 lint 这样的工具试图教给我们的。

对于 python 代码，样式摘要位于 PEP-257提供了很多有用的指南和一些例子。

快速查看我机器上的一些“好”代码 Andrea Gavana's Aquabutton.py我在下面包含了一段代码，但您可以查看完整代码 here - 我不得不说这是我打开的 Andrea's 的第一个模块，在字母表中处于早期，但我相信任何人都会这样做。

# --------------------------------------------------------------------------------- #
# 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:
#
# andrea.gavana@gmail.com
# andrea.gavana@maerskoil.com
#
# 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

剪辑

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()