注释

读没有注释代码的痛苦你我都体会过,好的注释不仅能让人轻松读懂你的程序,还能提升代码的逼格。注意注释是为了让别人看懂,而不是仅仅你自己。

文件注释

每一个文件都必须写文件注释,文件注释通常包含

  • 文件所在模块
  • 作者信息
  • 历史版本信息
  • 版权信息
  • 文件包含的内容,作用

一段良好文件注释的栗子:

  1. /*******************************************************************************
  2. Copyright (C), 2011-2013, Andrew Min Chang
  3. File name: AMCCommonLib.h
  4. Author: Andrew Chang (Zhang Min)
  5. E-mail: LaplaceZhang@126.com
  6. Description:
  7. This file provide some covenient tool in calling library tools. One can easily include
  8. library headers he wants by declaring the corresponding macros.
  9. I hope this file is not only a header, but also a useful Linux library note.
  10. History:
  11. 2012-??-??: On about come date around middle of Year 2012, file created as "commonLib.h"
  12. 2012-08-20: Add shared memory library; add message queue.
  13. 2012-08-21: Add socket library (local)
  14. 2012-08-22: Add math library
  15. 2012-08-23: Add socket library (internet)
  16. 2012-08-24: Add daemon function
  17. 2012-10-10: Change file name as "AMCCommonLib.h"
  18. 2012-12-04: Add UDP support in AMC socket library
  19. 2013-01-07: Add basic data type such as "sint8_t"
  20. 2013-01-18: Add CFG_LIB_STR_NUM.
  21. 2013-01-22: Add CFG_LIB_TIMER.
  22. 2013-01-22: Remove CFG_LIB_DATA_TYPE because there is already AMCDataTypes.h
  23. Copyright information:
  24. This file was intended to be under GPL protocol. However, I may use this library
  25. in my work as I am an employee. And my company may require me to keep it secret.
  26. Therefore, this file is neither open source nor under GPL control.
  27. ********************************************************************************/

文件注释的格式通常不作要求,能清晰易读就可以了,但在整个工程中风格要统一。

代码注释

好的代码应该是“自解释”(self-documenting)的,但仍然需要详细的注释来说明参数的意义、返回值、功能以及可能的副作用。

方法、函数、类、协议、类别的定义都需要注释,推荐采用Apple的标准注释风格,好处是可以在引用的地方alt+点击自动弹出注释,非常方便。

有很多可以自动生成注释格式的插件,推荐使用VVDocumenter

Screenshot

一些良好的注释:

  1. /**
  2. * Create a new preconnector to replace the old one with given mac address.
  3. * NOTICE: We DO NOT stop the old preconnector, so handle it by yourself.
  4. *
  5. * @param type Connect type the preconnector use.
  6. * @param macAddress Preconnector's mac address.
  7. */
  8. - (void)refreshConnectorWithConnectType:(IPCConnectType)type Mac:(NSString *)macAddress;
  9. /**
  10. * Stop current preconnecting when application is going to background.
  11. */
  12. -(void)stopRunning;
  13. /**
  14. * Get the COPY of cloud device with a given mac address.
  15. *
  16. * @param macAddress Mac address of the device.
  17. *
  18. * @return Instance of IPCCloudDevice.
  19. */
  20. -(IPCCloudDevice *)getCloudDeviceWithMac:(NSString *)macAddress;
  21. // A delegate for NSApplication to handle notifications about app
  22. // launch and shutdown. Owned by the main app controller.
  23. @interface MyAppDelegate : NSObject {
  24. ...
  25. }
  26. @end

协议、委托的注释要明确说明其被触发的条件:

  1. /** Delegate - Sent when failed to init connection, like p2p failed. */
  2. -(void)initConnectionDidFailed:(IPCConnectHandler *)handler;

如果在注释中要引用参数名或者方法函数名,使用||将参数或者方法括起来以避免歧义:

  1. // Sometimes we need |count| to be less than zero.
  2. // Remember to call |StringWithoutSpaces("foo bar baz")|

定义在头文件里的接口方法、属性必须要有注释!