From cbaba845785554242048fddb5dd8998f95147ab4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B0=D1=81=D0=B8=D0=BD=20=D0=90=D0=BD=D1=82=D0=BE?= =?UTF-8?q?=D0=BD=20=D0=9E=D0=BB=D0=B5=D0=B3=D0=BE=D0=B2=D0=B8=D1=87?= Date: Wed, 13 Feb 2019 13:06:11 +0000 Subject: [PATCH] Update Codestyle --- Codestyle.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Codestyle.md b/Codestyle.md index 5923f29..1671545 100644 --- a/Codestyle.md +++ b/Codestyle.md @@ -46,5 +46,15 @@ * Выражения в операторе for должны быть разделены пробелами. * За приведением типа должен следовать пробел. +4. Комментарии в Java делятся на 2 вида: комментарии реализации и документирующие комментарии. Комментарии реализации те же, что и в C++, обозначаются /* ... */ и //. Документирующие комментарии (известные как "doc comments" или "Javadoc") есть только в Java, и обозначаются /** ... */. Javadoc может быть извлечен из кода в HTML файл, используя инструмент javadoc. +Комментарии кода используются для описания отдельных строк/блоков кода или целого алгоритма. Комментарии для документирования используются, чтобы описать спецификацию кода, не зависящую от его реализации. +Комментарий можно считать полезным, если: +— достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой; +— в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт); +— комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath); +— в комментарии дан короткий ясный пример использования. + +Не стоит делать огромных комментариев, отделенных от основного кода строками из "*" или других символов. +Комментарии не должны содержать специальных символов, таких как символ конца страницы или backspace. \ No newline at end of file