romanov73/ng-tracker
1
0
Fork 0
Code Issues 18 Pull Requests 4 Projects Releases Wiki Activity

Update Codestyle

Васин Антон Олегович 2019-02-13 13:11:48 +00:00
parent 9891d2d3fa
commit 5830a90180
1 changed files with 4 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
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.