Code fragment-interesting comments

This article describes how to write readable code!

Reference: http://www.cnblogs.com/pengyingh/articles/2445826.html

I. Special comments

• Fixme
  • Source: Android/packages/apps/MMS/src/COM/Android/MMS/UI/slideview. Java
  • Ideographic: Code cannot work normally, and urgent repair is required

  • private Uri getSelectedUriFromMessageList(ListView listView, int position) {    ....    MessageListItem msglistItem = (MessageListItem) listView.getChildAt(position);    if (msglistItem == null) {        // FIXME: Should get the correct view. No such interface in ListView currently        // to get the view by position. The ListView.getChildAt(position) cannot        // get correct view since the list doesn't create one child for each item.        // And if setSelection(position) then getSelectedView(),        // cannot get corrent view when in touch mode.        return null;    }    ....    return null;}

• Todo
  • Source: Android/packages/apps/launcher/src/COM/Android/launcher2/allappslist. Java
  • Ideographic: functions to be processed

  • public void clear() {    data.clear();    // TODO: do we clear these too?    added.clear();    removed.clear();    modified.clear();}

• Xxx
  • Source: Android/packages/apps/Alibaba clock/src/COM/Android/Alibaba clock/alarms. Java
  • Ideographic: although functions are implemented, the processing method remains to be discussed.

  •     /**     * Sets alert in AlarmManger and StatusBar.  This is what will     * actually launch the alert when the alarm triggers.     *     * @param alarm Alarm.     * @param atTimeInMillis milliseconds since epoch     */    private static void enableAlert(Context context, final Alarm alarm,            final long atTimeInMillis) {        ....        Intent intent = new Intent(ALARM_ALERT_ACTION);        // XXX: This is a slight hack to avoid an exception in the remote        // AlarmManagerService process. The AlarmManager adds extra data to        // this Intent which causes it to inflate. Since the remote process        // does not know about the Alarm class, it throws a        // ClassNotFoundException.        //        // To avoid this, we marshall the data ourselves and then parcel a plain        // byte[] array. The AlarmReceiver class knows to build the Alarm        // object from the byte[] array.        Parcel out = Parcel.obtain();        alarm.writeToParcel(out, 0);        out.setDataPosition(0);        intent.putExtra(ALARM_RAW_DATA, out.marshall());        ....    }

2. Make comments more expressive

• Example

  • // Example: Strip("ab", "a") return "b"public String Strip(String src, String chars){....}

• Digit

  • // VideoId -> VideoURLHashMap<Integer, String> map = new HashMap<Integer, String>();

• Vivid description

  • <!-- Set of tips to show the user.     First line is the tip title, which is shown in bold on its own line.     All subsequent text is placed into the tip body.     The occurrence of @drawable/foo causes the bitmap drawable named "foo"     to be displayed to the right of the tip text.     Example for tip #1:      _____________________________________________     \_/     |                                             |   /._.\     |  See all your apps.         [all_apps.png]   > U|   |U     |  Touch the Launcher icon.                   |   |___|     |_____________________________________________|    U U--><string-array name="tips">    <!-- Tip: Where the launcher icon is and what it does. With icon. -->    <item>See all your apps.\n    Touch the Launcher icon. @drawable/all_apps</item>