Заставить разработчиков добавлять комментарии в функции

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

Как заставить разработчиков добавлять комментарии перед запуском функции (как показано ниже)?

/**
* This function returns a string hello
* @author Sahil Purav
*/
myfunction(): string {
   return 'hello';
}

typescript tsconfig tslint
person Sahil Purav    schedule 30.12.2017    source источник
comment
Добавьте проверку кода в процесс вместе со стандартами кодирования   -  person Ed Heal    schedule 30.12.2017
comment
проблема уже открыта на github.com/palantir/tslint/issues/623   -  person santosh singh    schedule 30.12.2017
comment
Он есть... Но мы работаем в автоматизированном мире. Разве не хорошо иметь правило tslint, чтобы даже до проверки кода у нас были комментарии к функциям, чтобы рецензент больше концентрировался на логике, написанной разработчиком, а не на отсутствующем стандарте.   -  person Sahil Purav    schedule 30.12.2017
comment
Через некоторое время стандарт кодирования станет второй натурой как для программиста, так и для рецензента.   -  person Ed Heal    schedule 30.12.2017
comment
Несмотря на то, что технический подход, без сомнения, применим, как предлагает @Ed, в любом случае необходимо давать рекомендации и поощрять людей, демонстрируя преимущества написания хороших комментариев. До этого вы можете ожидать, что люди обойдут технические требования, написав в комментарии любую чепуху, просто чтобы система перестала жаловаться - и это, возможно, хуже, чем если бы они просто не прокомментировали это... (и с точки зрения обслуживания - кто-то должен будет исправить комментарий позже (или, что более вероятно, забудете это сделать, и он просто будет висеть целую вечность))   -  person Jon Clements♦    schedule 30.12.2017
comment
Я согласен с вами @JonClements. Но у нас есть процесс запуска lint перед отправкой кода на промежуточный сервер. Если tslint не работает, код не будет загружен на сервер. В этом случае разработчику придется добавить комментарии. Кроме того, если у нас есть комментарии по поводу функции, это действительно не повредит. Я бы по-прежнему придерживался фразы что-то лучше, чем ничего   -  person Sahil Purav    schedule 30.12.2017
comment
@Sahil Предположим, вы можете использовать этот подход - по моему опыту - нет ничего лучше, чем что-то вводящее в заблуждение / неточное / просто шум ...   -  person Jon Clements♦    schedule 30.12.2017

Ответы (1)


arrow_upward
0
arrow_downward

Я провел еще несколько исследований по этому вопросу и обнаружил, что в tslint есть правило для принудительного применения комментариев, и, что хорошо, оно легко настраивается.

Я использовал следующее правило, которое удовлетворяет моему требованию:

"completed-docs": [
      true,
      {
        "enums": true,
        "functions": {
          "visibilities": ["exported"]
        },
        "methods": {
          "location": "instance",
          "privacies": ["public", "protected"]
        }
      }
    ]

Для получения дополнительной информации проверьте это - https://palantir.github.io/tslint/rules/completed-docs/

person Sahil Purav    schedule 30.12.2017