История изменений
Исправление
Legioner,
(текущая версия)
:
Правда посредине. С одной стороны если какой-то комментарий можно заменить грамотным именованием, то нужно так и сделать. Т.е. вместо
/**
* Returns first name
*/
String getName()
надо писать
String getFirstName()
С другой стороны не всегда в идентификатор можно или разумно вмещать всю информацию, которую хочется передать. В этом случае надо писать комментарий.
Надо писать
/**
* Returns first name if user data has been initialized or null
*/
String getFirstName()
не надо писать
String getFirstNameIfDataHasBeenInitializedOrNull();
хотя могут быть случаи, когда и такой вариант стоит выбрать. Например
void unsafeImmediateServiceShutdownCausingLossOfData()
вместо
/**
* Imediately shuts down the service, causes loss of data
*/
void immediateShutdown()
т.к. использоваться будет редко, а в глаза бросаться должно.
А самые грамотные программисты ещё и расписывают всякую полезную ерунду, которую кодом выразить принципиально невозможно. Я до такого ещё не дорос. Но в целом перед началом кода функции, например, описывают, почему эта функция так написана. Условный пример:
/*
* The following code uses bubble-sort algorithm because of better cache-locality.
* It evicts less bytes of L1 cache than other algorithms and input size is insignificant
* to cause issues because of quadratic complexity.
*/
...
Примерно как я себе это представляю, нужно написать код, потом прочитать его свежим взглядом, представив себя на месте человека, который его первый раз видит, подумать, зачем он этот код читает, с какой целью и добавить комментарии, чтобы облегчить ему его задачу. Эдакий локальный FAQ.
Исходная версия
Legioner,
:
Правда посредине. С одной стороны если какой-то комментарий можно заменить грамотным именованием, то нужно так и сделать. Т.е. вместо
/**
* Returns first name
*/
String getName()
надо писать
String getFirstName()
С другой стороны не всегда в идентификатор можно или разумно вмещать всю информацию, которую хочется передать. В этом случае надо писать комментарий.
Надо писать
/**
* Returns first name if user data has been initialized or null
*/
String getFirstName()
не надо писать
String getFirstNameIfDataHasBeenInitializedOrNull();
хотя могут быть случаи, когда и такой вариант стоит выбрать. Например
void unsafeImmediateServiceShutdownCausingLossOfData()
вместо
/**
* Imediately shuts down the service, causes loss of data
*/
void immediateShutdown()
т.к. использоваться будет редко, а в глаза бросаться должно.
А самые грамотные программисты ещё и расписывают всякую полезную ерунду, которую кодом выразить принципиально невозможно. Я до такого ещё не дорос. Но в целом перед началом кода функции, например, описывают, почему эта функция так написана. Условный пример:
/*
* The following code uses bubble-sort algorithm because of better cache-locality.
* It evicts less bytes of L1 cache than other algorithms and input size is insignificant
* to cause issues because of quadratic complexity.
*/
...