-
Notifications
You must be signed in to change notification settings - Fork 3
[C]omments
“Every time you write a comment, you should grimace and feel the failure of your ability of expression.”
― Robert C. Martin
It is inappropriate for a comment to hold information better held in a different kind of system such as your source code control system, your issue tracking system, or any other record-keeping system. Change histories, for example, just clutter up source files with volumes of historical and uninteresting text. In general, meta-data such as authors, lastmodified-date, SPR number, and so on should not appear in comments. Comments should be reserved for technical notes about the code and design.
[C01]: Неуместная информация
В комментариях неуместно размещать информацию, которую удобнее хранить в других источниках: в системах управления исходным кодом, в системах контроля версий и в других системах протоколирования. Например, история изменений только загромождает исходные файлы длинным историческим и малоинтересным текстом. Метаданные (авторы, дата последней модификации и т. д.) в общем случае также неуместны в комментариях. Комментарии должны быть зарезервированы для технической информации о коде и его архитектуре.
[C01]: Недоречна інформація
У коментарях неприйнятно розміщувати інформацію, яка краще зберігається в інших джерелах, таких як системи управління вихідним кодом, системи контролю версій та інші системи журналювання. Наприклад, історія змін лише завантажує вихідні файли довгою історичною та малоцікавою інформацією. Метадані (автори, дата останньої модифікації тощо) також в загальному випадку не підходять для коментарів. Коментарі мають бути зарезервовані для технічної інформації про код та його архітектуру.
A comment that has gotten old, irrelevant, and incorrect is obsolete. Comments get old quickly. It is best not to write a comment that will become obsolete. If you find an obsolete comment, it is best to update it or get rid of it as quickly as possible. Obsolete comments tend to migrate away from the code they once described. They become floating islands of irrelevance and misdirection in the code.
[C02] Устаревший комментарий
Комментарий, содержимое которого потеряло актуальность, считается устаревшим. Комментарии стареют довольно быстро. Не пишите комментарии, которые с течением времени устареют. Обнаружив устаревший комментарий, обновите его или избавьтесь от него как можно быстрее. Устаревшие комментарии часто «отрываются» от кода, который они когда-то описывали. Так в вашем коде появляются плавучие островки недостоверности и бесполезности.
[C02] Застарілий коментар
Коментар, зміст якого втратив актуальність, вважається застарілим. Коментарі застарівають досить швидко. Не пишіть коментарі, які з часом застаріють. Якщо ви виявили застарілий коментар, оновіть його або відмовтесь від нього якомога швидше. Застарілі коментарі часто "відпливають" від коду, який вони колись описували. Так у вашому коді з'являються плавучі острови недостовірності та некорисності.
A comment is redundant if it describes something that adequately describes itself. Comments should say things that the code cannot say for itself.
[C03]: Избыточный комментарий
Избыточным считается комментарий, описывающий то, что и так очевидно. Комментарии должны говорить то, что не может сказать сам код.
[C03]: Зайвий коментар
Зайвим вважається коментар, що описує очевидну річ. Коментарі мають повідомляти про те, що код не може сказати сам за себе.
A comment worth writing is worth writing well. If you are going to write a comment, take the time to make sure it is the best comment you can write. Choose your words carefully. Use correct grammar and punctuation. Don’t ramble. Don’t state the obvious. Be brief.
[C04]: Плохо написанный комментарий
Если уж вы беретесь за написание комментария, напишите его хорошо. Не жалейте времени и позаботьтесь о том, чтобы это был лучший комментарий, который вы способны создать. Тщательно выбирайте слова. Следите за правильностью орфографии и пунктуации. Не пишите сумбурно. Не объясняйте очевидное. Будьте лаконичны.
[C04]: Погано написаний коментар
Якщо ви беретеся за написання коментаря, напишіть його добре. Не шкодуйте часу та подбайте про те, щоб це був найкращий коментар, який ви здатні створити. Ретельно вибирайте слова. Слідкуйте за правильністю орфографії та пунктуації. Не пишіть сумбурно. Чи не пояснюйте очевидне. Будьте лаконічні.
It makes me crazy to see stretches of code that are commented out. Who knows how old it is? Who knows whether or not it’s meaningful? Yet no one will delete it because everyone assumes someone else needs it or has plans for it.
That code sits there and rots, getting less and less relevant with every passing day. It calls functions that no longer exist. It uses variables whose names have changed. It follows conventions that are long obsolete. It pollutes the modules that contain it and distracts the people who try to read it. Commented-out code is an abomination!
When you see commented-out code, delete it! Don’t worry, the source code control system still remembers it. If anyone really needs it, he or she can go back and check out a previous version. Don’t suffer commented-out code to survive.
[C05]: Закомментированный код
Фрагменты закомментированного кода выводят меня из себя. Кто знает, когда был написан этот код? Кто знает, есть от него какая-нибудь польза или нет? Однако никто не удаляет закомментированный код — все считают, что он понадобится кому-то другому.
Этот код только попусту занимает место, «загнивая» и утрачивая актуальность с каждым днем. В нем вызываются несуществующие функции. В нем используются переменные, имена которых давно изменились. В нем соблюдаются устаревшие конвенции. Он загрязняет модуль, в котором он содержится, и отвлекает людей, которые пытаются его читать. Закомментированный код отвратителен!
Увидев закомментированный код, удалите его! Не беспокойтесь, система управления исходным кодом его не забудет. Если кому-то этот код действительно понадобится, то он сможет вернуться к предыдущей версии. Не позволяйте закомментированному коду портить вам жизнь.
[C05]: Закоментований код
Фрагменти закоментованого коду виводять мене із себе. Хто знає, коли було написано цей код? Хто знає, чи є від нього якась користь чи ні? Однак ніхто не видаляє закоментований код – усі вважають, що він знадобиться комусь іншому.
Цей код тільки марно займає місце, «загнивая» і втрачаючи актуальність з кожним днем. У ньому викликаються неіснуючі функції. У ньому використовують змінні, імена яких давно змінилися. У ньому дотримуються застарілі конвенції. Він забруднює модуль, у якому міститься, і відволікає людей, які намагаються його читати. Закоментований код огидний!
Побачивши закоментований код, видаліть його! Не турбуйтеся, система керування вихідним кодом його не забуде. Якщо комусь цей код дійсно знадобиться, він зможе повернутися до попередньої версії. Не дозволяйте закоментованому коду псувати вам життя.
This wiki document contains a lot of information, please take your time and read these carefully.
If you run into any trouble, you may start by understanding how this works.
Be sure to read the CONTRIBUTING guidelines before reporting a new issue or open a pull request.
If you have any questions about the Heuristics for "Clear Code" usage or want to share some information with the our community, please go to one of the following places: