Хабр Курсы для всех
РЕКЛАМА
Большая витрина: от крупнейших школ до частных авторов. Сравнивайте по цене, длительности, формату и выбирайте самый подходящий курс!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 17
Совсем без комментариев тоже плохо.
Если у вас комментарии в коде — по ним можно автоматически сгенерировать документацию по API, то есть ничего не противоречит:
да просто потому, что комментарии в коде легче поддерживать в актуальном состоянии, чем если код отдельно, а комментарии совсем отдельно.
Если у вас комментарии в коде — по ним можно автоматически сгенерировать документацию по API, то есть ничего не противоречит:
С точки зрения пользователя лучше, чтобы документация была в отдельном файле.
Зачем при этом еще и комментировать весь код?
да просто потому, что комментарии в коде легче поддерживать в актуальном состоянии, чем если код отдельно, а комментарии совсем отдельно.
Солидаризуюсь — я имел дело с C++ проектами, в которых использовался Doxygen, это было удобно (разметка комментариев легковесная, производная от Javadoc — в сравнении с, например более тяжёлой XML разметкой Sandcastle — и сгенерированная документация выглядит пристойно).
Я не очень понимаю, в чем сложность поддержки. К очередному релизу пишем очередную документацию. Разработка делается для пользователей, значит надо исходить из их интересов и в любом случае предоставить отдельный файл. Тогда зачем писать комментарии в код?
Если работает команда, нужно сначала сформулировать требования к каждому программисту. В таком случае документация будет готова еще до программы.
Если работает команда, нужно сначала сформулировать требования к каждому программисту. В таком случае документация будет готова еще до программы.
Но согласитесь, что проще написать комментарий к методу прямо в коде, а не открывать отдельный файл, и добавлять туда описание этого метода с комментарием. Аналогично, если требуется изменить поведение какого-либо метода.
А отдельный файл документации для пользователя потом соберёт скрипт по этим комментариям. Или даже несколько вариантов документации с разной детализацией/оформлением, например.
А отдельный файл документации для пользователя потом соберёт скрипт по этим комментариям. Или даже несколько вариантов документации с разной детализацией/оформлением, например.
Я не согласен. На мой взгляд проще написать стройное описание в отдельный файл. Открыть отдельный файл практически так же просто, как и написать комментарий. это все касаемо тех случаев, когда нужна документация для пользователей.
Если экспортировать методы не предполагается, названия метода должно быть достаточно для того чтобы понять что он делает.
Если экспортировать методы не предполагается, названия метода должно быть достаточно для того чтобы понять что он делает.
Нельзя возводить самодокументацию в абсолют. К примеру: вот мне дали изучать сложный и запутанный проект. С задачей внеси небольшие изменения.
И понеслось… как построен проект, каковы основные идеи и стратегии при проектировании надо выбирать, в каких единицах измерений надо считать, какие классы уже есть, может мне не надо изобретать велосипед, а дернуть уже имеющуся функцию или использовать имеющийся класс.
Я уже не говорю про то, что когда вы реализуете модель, то лучше выбирать обозначение переменных такими же как в источнике и стороннему человеку это будет не понятно.
Самодокументация должна отвечать как это сделано, что подавать на вход и набросать черновик того, как все что написано надо использовать, но не более.
Если в двух словах то документация должна ввести стороннего человека до того как он тронет ваш код. А самодокументация должна помогать в процессе.
И понеслось… как построен проект, каковы основные идеи и стратегии при проектировании надо выбирать, в каких единицах измерений надо считать, какие классы уже есть, может мне не надо изобретать велосипед, а дернуть уже имеющуся функцию или использовать имеющийся класс.
Я уже не говорю про то, что когда вы реализуете модель, то лучше выбирать обозначение переменных такими же как в источнике и стороннему человеку это будет не понятно.
Самодокументация должна отвечать как это сделано, что подавать на вход и набросать черновик того, как все что написано надо использовать, но не более.
Если в двух словах то документация должна ввести стороннего человека до того как он тронет ваш код. А самодокументация должна помогать в процессе.
Если есть сложные цепочки, почему бы не описать их в отдельном файле?
У нас есть стандарты оформления документации на ПО: ГОСТы групп 19 «Единая система программной документации» и 34 «Автоматизированные системы» (для иностранных проектов есть однозначное соответствие). Поэтому вы обязаны представить заказчику (по ГОСТ 19.101-77) текст программы (индекс 12) и описание программы (индекс 13) в любом случае. Все эти размышления по поводу надо или не надо документировать ПО находятся на уровне программистского детсада, т.е. незнания ГОСТов и своеобразного халтурного способа разработки ПО.
У нас есть стандарты оформления документации на ПО: ГОСТы групп 19 «Единая система программной документации» и 34 «Автоматизированные системы» (для иностранных проектов есть однозначное соответствие). Поэтому вы обязаны представить заказчику (по ГОСТ 19.101-77) текст программы (индекс 12) и описание программы (индекс 13) в любом случае. Все эти размышления по поводу надо или не надо документировать ПО находятся на уровне программистского детсада, т.е. незнания ГОСТов и своеобразного халтурного способа разработки ПО.
В Haskell роль докумнентации хорошо играют типы. Для функций и конструкторов там важно подбирать значимые имена. А для локальных переменных особой необходимости нет — как правило их область видимости в несколько строк. Да и часто можно вообще переменных не использовать, комбинируя функции работы с контейнерами.
Но в ОО-языках с их динамичностью без комментариев обходиться тяжело.
Но в ОО-языках с их динамичностью без комментариев обходиться тяжело.
Автор, код в студию. Желательно кусок побольше.
Было бы неплохо, на мой взгляд, снабдить всё это примерами — как, по-вашему, делать правильно, а как нет.
что опять? :)
все уже поняли что нужна золотая середина
все уже поняли что нужна золотая середина
Я чаще всего комментарии использую что бы сохранить в коде ответ на вопрос «Какого фига именно так хитро зачем я это написал?», а вот на вопрос «Что делает это кусок кода?» — да, действительно, сам кусок кода и должен отвечать.
Сколько видел умников, которые говорили, что их код самодокументирующийся, всё отлично видно из юнит-тестов, «код задокументирован на языке Си»…
Через время сами в своём дер.ме разобраться не могли.
Через время сами в своём дер.ме разобраться не могли.
Стремиться надо к максимальной понятности и поддерживаемости кода, а количество комментариев — вещь производная.
(Совершенный код, 34.9)
Догматичные методологии и разработка высококачественного ПО исключают друг друга. Заполняйте свой интеллектуальный инструментарий альтернативными подходами к программированию и улучшайте навык выбора инструмента, лучше всего подходящего для работы.
(Совершенный код, 34.9)
Код, сам по себе, объясняет компилятору, КАК он хочет что-то сделать.
Комментарии в коде пишутся для того, чтобы было ясно ЧТО должно быть сделано.
Если взять ваш пример, то можно найти целую кучу низкоуровневых операций и приведений типов.
Если вы называете переменные не в шахматном стиле, e2 — e4, то это еще не делает ваш код самодокументируемым.
Например, метод MyFrame::loadHandlers(), можно разбить на несколько методов, для каждой магической операции в нем.
Методам — дать хорошие имена, которые говорят, что они делают, а не как.
Вот пример:
Магической операции вроде:
Дать имя, которое говорит, что же эта операция таки проверяет:
Комментарии в коде пишутся для того, чтобы было ясно ЧТО должно быть сделано.
Если взять ваш пример, то можно найти целую кучу низкоуровневых операций и приведений типов.
Если вы называете переменные не в шахматном стиле, e2 — e4, то это еще не делает ваш код самодокументируемым.
Например, метод MyFrame::loadHandlers(), можно разбить на несколько методов, для каждой магической операции в нем.
Методам — дать хорошие имена, которые говорят, что они делают, а не как.
Вот пример:
Магической операции вроде:
if (!dirHandlers.GetFirst( &sLibName, wxEmptyString, wxDIR_FILES)) return;Дать имя, которое говорит, что же эта операция таки проверяет:
if (directoryIsEmpty(&sLibName, wxEmptyString, wxDIR_FILES)) return;На мой взгляд и так очевидно, что делает эта операция. Зачем множить сущности?
Да, это была простая операция. И я догадался что она делает, хоть и были сомнения.
Тем не менее, для достижения самодокументированого кода, необходимо выносить логически завершенные блоки кода в отдельные методы. Тогда код будет рассказывать ЧТО он делает, а не только КАК он это делает.
Это правило должно применяться как к одной строчки кода, так и к 5-ти, например.
Если не хотите множить сущности, то всегда можно добавить комментарий:
или
А если не хотите добавлять комментарий — тоже не беда. Рано или поздно тот, кто будет читать код, с ним все равно разберется.
Тем не менее, для достижения самодокументированого кода, необходимо выносить логически завершенные блоки кода в отдельные методы. Тогда код будет рассказывать ЧТО он делает, а не только КАК он это делает.
Это правило должно применяться как к одной строчки кода, так и к 5-ти, например.
Если не хотите множить сущности, то всегда можно добавить комментарий:
// Return if directory is emptyили
// Return ifthere are no .dll files in the directoryА если не хотите добавлять комментарий — тоже не беда. Рано или поздно тот, кто будет читать код, с ним все равно разберется.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Здравствуйте, меня зовут SiTLar, мне 30 лет и я пишу самодокументирующийся код