LINUX.ORG.RU

История изменений

Исправление 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.
 */
...