Commenting code (Decision)

Что комментируем:

• Функции
• Файлы
• Классы
• Не очевидные строки кода
• Глобальные переменные
  
  

Правильное оформление комментариев:

1. PEP 257 - где и как правильно писать комментарий

2. Epydoc Fields - правильная структура комментария

Пример:

def getRawObjectById(objectId):

    """

    Returns object from db by its id

    @param objectId: Desired object's id

    @return: object from db

    @rtype: dict

    """

    collection = getObjects()

    return collection.find_one({"_id": objectId})

Для комментирования функций в JS используем точно такое же оформление.

Пример:

function delMarkerOnMap(i) {

    /*

     *Removes marker from map

     *@param i: object number

     *@type i: int

     */

    map.removeLayer(MarkerList[i]);

    removeShowOnMap(ObjListOnMap[i].id);

    delete ObjListOnMap[i];

}