Question

很久以前，我快速浏览了一些代码（PERL ... urp），其中一位经理正在编写并被他在代码中使用的横幅/标题系统震惊。我没有机会详细研究他的代码，但只是从屏幕上的横幅评论中我可以很容易地告诉代码的意图，即使是在很远的地方。

不幸的是，很久以前我们的谈话并不适合我说：“是的，好好忘记我们的dot-com创业公司上厕所，我可以记下你的编码风格吗？”

多年以后，我还没有达到一种高级评论风格，这种评论风格与我当天看到的（现在可能是神话般的）代码一样清晰。

当我说“横幅”时，我指的是许多程序员用来在代码中创建更高级别设计的高级块分区/标题。它们通常由简单的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的第一个模块，在字母表的早期，但我相信任何人都会这样做。

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

评论Banner / Header最佳实践/示例？

1 个答案: