Вопросы с тегом «comments»

Закрыто . Этот вопрос основан на мнении . В настоящее время он не принимает ответы. Хотите улучшить этот вопрос? Обновите вопрос, чтобы ответить на него фактами и цитатами, отредактировав этот пост . Закрыто 4 года назад . Для комментариев контроля версий, что другие пользователи рекомендуют - прошедшее или настоящее время? …

12 comments  source-code 

У меня довольно большая частная кодовая база, которая развивается уже около десяти лет. Я не использую phpDocumentor, но поскольку использование разделов с докблоком стало довольно стандартным в проектах с открытым исходным кодом, я принял написание докблоков для всех открытых методов в моем репозитории. Большинство блоков просто содержат небольшое описание и …

12 php  comments 

Я работаю над проектом «спагетти-кода», и пока я исправляю ошибки и внедряю новые функции, я также провожу некоторый рефакторинг, чтобы сделать код модульно-тестируемым. Код часто настолько тесно связан или сложен, что исправление небольшой ошибки приводит к переписыванию множества классов. Поэтому я решил провести где-то в коде линию, где я прекращаю …

11 refactoring  comments 

Существуют ли общие практики для комментирования регулярных выражений: встроенные комментарии, ссылающиеся на различные части RegEx, или общие комментарии для всех выражений?

11 documentation  coding-style  comments 

Я разговаривал с коллегой сегодня. Мы работаем над кодом для двух разных проектов. В моем случае я единственный человек, работающий над моим кодом; в ее случае несколько человек работают над одной и той же кодовой базой, в том числе студенты-кооператоры, которые приходят и уходят довольно регулярно (каждые 8-12 месяцев). Она …

11 coding-style  team  comments 

Я хотел бы знать, как лучше всего добавить комментарий для идентификации устаревшего класса в Java. Должен ли я удалить предыдущий комментарий, добавленный в начало класса, который помогает другому программисту знать, для чего этот класс, или я должен добавить его под комментарием?

11 java  code-quality  api  comments 

Когда я пишу небольшие сценарии для себя, я складываю свой код с комментариями (иногда я комментирую больше, чем код). Многие люди, с которыми я общаюсь, говорят, что я должен документировать эти сценарии, даже если они являются личными, поэтому, если я когда-нибудь продам их, я буду готов. Но разве комментарии не …

11 documentation  comments 

Раньше я был поклонником требования XML-комментариев для документации. С тех пор я передумал по двум основным причинам: Как и хороший код, методы должны быть понятны. На практике большинство XML-комментариев представляют собой бесполезный шум, который не дает никакой дополнительной ценности. Много раз мы просто используем GhostDoc для генерации общих комментариев, и …

10 .net  programming-practices  development-process  documentation  comments 

Я сторонник надлежащим образом документированного кода, и я хорошо осведомлен о возможных его недостатках . Это выходит за рамки этого вопроса. Мне нравится следовать правилу добавления комментариев XML для каждого публичного участника, учитывая, насколько мне нравится IntelliSense в Visual Studio. Однако существует одна форма избыточности, которая беспокоит даже такого чрезмерного …

10 documentation  comments  intellisense 

Является ли хорошей практикой писать комментарии для широко известных методов, таких как equals, compareTo и т. Д.? Рассмотрим приведенный ниже код. /** * This method compares the equality of the current object with the object of same type */ @Override public boolean equals(Object obj) { //code for equals } Моя …

10 java  comments 

Я читаю « Чистый код » Роберта С. Мартина, и эта фраза TILTнеобъяснимым образом появляется в некоторых примерах кода. Пример (это на Java, кстати): ... public String errorMessage() { switch (status) { case ErrorCode.OK: // TILT - Should not get here. return ""; case ErrorCode.UNEXPECTED_ARGUMENT: return "Unexpected argument"; case ErrorCode.MISSING_ARGUMENT: …

9 java  clean-code  comments  conventions 

Я собираюсь покинуть проект, и прежде чем я уйду, мой начальник попросил меня документировать код (я не очень хорошо задокументировал). Это не имеет большого значения, проект не очень сложный. Но я нахожу в своей документации места, где я хотел бы сказать: «В строке XYZ обратите внимание, что происходит то-то и …

9 documentation  comments 

Я хочу написать Javadoc в сухом виде. Но документ оракула о Javadoc говорит, что напишите то же самое снова в комментарии метода перегрузки. Могу ли я избежать повторения?

9 documentation  comments  dry  javadocs 

В настоящее время этот вопрос не очень подходит для нашего формата вопросов и ответов. Мы ожидаем, что ответы будут подтверждены фактами, ссылками или опытом, но этот вопрос, скорее всего, вызовет дебаты, споры, опрос или расширенное обсуждение. Если вы считаете, что этот вопрос можно улучшить и, возможно, вновь открыть, обратитесь за …

9 comments 

Это может быть глупый вопрос, но это было в моей голове некоторое время, и я не могу найти достойного ответа где-либо еще. У меня есть учитель, который говорит, что мы должны явно перечислить каждый параметр с описанием, даже если он только один. Это приводит к большому количеству повторений: double MyFunction(const …

9 documentation  comments  coding-style