diff --git a/Codestyle.md b/Codestyle.md index 6cb79f3..4f3bed8 100644 --- a/Codestyle.md +++ b/Codestyle.md @@ -51,10 +51,10 @@ Комментарии кода используются для описания отдельных строк/блоков кода или целого алгоритма. Комментарии для документирования используются, чтобы описать спецификацию кода, не зависящую от его реализации. Комментарий можно считать полезным, если: -1. достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой; -2. в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт); -3. комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath); -4. в комментарии дан короткий ясный пример использования. +* достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой; +* в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт); +* комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath); +* в комментарии дан короткий ясный пример использования. Не стоит делать огромных комментариев, отделенных от основного кода строками из "*" или других символов. Комментарии не должны содержать специальных символов, таких как символ конца страницы или backspace. \ No newline at end of file